@hkdigital/lib-core 0.3.15 → 0.4.3

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

@@ -0,0 +1,395 @@
+/**
+ * Shared error formatting logic for logging adapters
+ * 
+ * This module contains reusable functions for analyzing and formatting
+ * errors with enhanced stack trace detection and error type identification.
+ */
+
+/**
+ * Find the most relevant frame index for highlighting in stack traces
+ * 
+ * @param {Error} error - The error object
+ * @param {string[]} cleanedStack - Array of cleaned stack trace frames
+ * @returns {number} Index of the most relevant frame to highlight
+ */
+export function findRelevantFrameIndex(error, cleanedStack) {
+  // Check if this is a LoggerError - look for Logger.error call
+  if (error.name === 'LoggerError') {
+    const loggerErrorIndex = cleanedStack.findIndex(frame => 
+      frame.includes('Logger.error') && frame.includes('logger/Logger.js')
+    );
+    if (loggerErrorIndex >= 0 && loggerErrorIndex + 1 < cleanedStack.length) {
+      return loggerErrorIndex + 1;
+    }
+  }
+
+  if (error.name === 'ValiError') {
+    // Look for expect_ function first, user code is right after (handle Node.js format)
+    const expectIndex = cleanedStack.findIndex(frame => 
+      frame.includes('expect_') || frame.includes('Module.expect_')
+    );
+    if (expectIndex >= 0 && expectIndex + 1 < cleanedStack.length) {
+      return expectIndex + 1;
+    }
+    
+    // If no expect_ function, look for valibotParser, user code is right after
+    const valibotIndex = cleanedStack.findIndex(frame => frame.includes('valibotParser'));
+    if (valibotIndex >= 0 && valibotIndex + 1 < cleanedStack.length) {
+      return valibotIndex + 1;
+    }
+  }
+
+  if (error.name === 'DetailedError') {
+    // Check if this DetailedError was created by Logger.error - look for Logger.error call first
+    // Handle both Firefox format (error@file) and Node.js format (at Logger.error (file))
+    const loggerErrorIndex = cleanedStack.findIndex(frame => 
+      (frame.includes('Logger.error') && frame.includes('logger/Logger.js')) ||
+      (frame.includes('error@') && frame.includes('logger/Logger.js'))
+    );
+    if (loggerErrorIndex >= 0 && loggerErrorIndex + 1 < cleanedStack.length) {
+      return loggerErrorIndex + 1;
+    }
+    
+    // Look for rethrow, user code is right after (handle both Firefox and Node.js format)
+    const rethrowIndex = cleanedStack.findIndex(frame => 
+      frame.includes('rethrow@') || frame.includes('at rethrow (')
+    );
+    if (rethrowIndex >= 0 && rethrowIndex + 1 < cleanedStack.length) {
+      return rethrowIndex + 1;
+    }
+  }
+
+  if (error.name === 'PromiseError') {
+    // Look for HkPromise methods, user code is right after
+    const hkPromiseIndex = cleanedStack.findIndex(frame => 
+      frame.includes('reject@') || 
+      frame.includes('tryReject@') || 
+      frame.includes('setTimeout@') || 
+      frame.includes('cancel@') || 
+      frame.includes('tryCancel@')
+    );
+    if (hkPromiseIndex >= 0 && hkPromiseIndex + 1 < cleanedStack.length) {
+      return hkPromiseIndex + 1;
+    }
+  }
+
+  if (error.name === 'HttpError') {
+    // Find the last frame containing http-request.js, then highlight the next one
+    let lastHttpIndex = -1;
+    for (let i = 0; i < cleanedStack.length; i++) {
+      if (cleanedStack[i].includes('network/http/http-request.js')) {
+        lastHttpIndex = i;
+      }
+    }
+    if (lastHttpIndex >= 0 && lastHttpIndex + 1 < cleanedStack.length) {
+      return lastHttpIndex + 1;
+    }
+  }
+
+  // Default to first frame
+  return 0;
+}
+
+/**
+ * Detect error metadata for structured logging and display
+ * 
+ * @param {Error} error - The error object
+ * @param {string[]} cleanedStack - Array of cleaned stack trace frames
+ * @returns {import('./typedef.js').ErrorSummaryMeta} Error metadata
+ */
+export function detectErrorMeta(error, cleanedStack) {
+  const userFunctionName = extractUserFunctionName(error, cleanedStack);
+  const relevantFrameIndex = findRelevantFrameIndex(error, cleanedStack);
+
+  // Check if it's a LoggerError
+  if (error.name === 'LoggerError') {
+    return {
+      category: 'logger',
+      method: 'logger.error',
+      origin: userFunctionName,
+      relevantFrameIndex
+    };
+  }
+
+  // Check if it's a rethrow error
+  if (error.name === 'DetailedError') {
+    // Check if this DetailedError was created by Logger.error
+    const cleanedStackArray = cleanedStack || [];
+    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) {
+      return {
+        category: 'logger',
+        method: 'logger.error',
+        origin: userFunctionName,
+        relevantFrameIndex
+      };
+    }
+    
+    // Otherwise it's a regular rethrow error
+    return {
+      category: 'rethrow',
+      method: 'rethrow',
+      origin: userFunctionName,
+      relevantFrameIndex
+    };
+  }
+
+  // Check if it's a PromiseError (HkPromise)
+  if (error.name === 'PromiseError') {
+    const hkPromiseMethod = getHkPromiseMethod(cleanedStack);
+    return {
+      category: 'promise',
+      method: hkPromiseMethod ? `hkpromise.${hkPromiseMethod}` : 'hkpromise',
+      origin: userFunctionName,
+      relevantFrameIndex
+    };
+  }
+
+  // Check if it's an HttpError
+  if (error.name === 'HttpError') {
+    const httpMethod = getHttpMethod(cleanedStack);
+    return {
+      category: 'http',
+      method: httpMethod || 'http',
+      origin: userFunctionName,
+      relevantFrameIndex
+    };
+  }
+
+  // Check if it's a valibot validation error
+  if (error.name === 'ValiError' && cleanedStack.length > 0) {
+    // Look for our valibotParser wrapper function in the stack
+    const valibotFrame = cleanedStack.find(frame => 
+      frame.includes('valibotParser')
+    );
+    
+    // Also check if it's called via an expect_ function (handle Node.js format)
+    const expectFrame = cleanedStack.find(frame => 
+      frame.includes('expect_') || frame.includes('Module.expect_')
+    );
+    
+    if (valibotFrame || expectFrame) {
+      return {
+        category: 'validation',
+        method: expectFrame ? 'expect' : 'validation',
+        origin: userFunctionName,
+        relevantFrameIndex
+      };
+    }
+  }
+
+  // Default case
+  return {
+    category: 'error',
+    method: 'error',
+    origin: userFunctionName,
+    relevantFrameIndex
+  };
+}
+
+/**
+ * Format error metadata for console display
+ * 
+ * @param {{category: string, method: string, origin?: string|null}} errorMeta - Error metadata
+ * @returns {string} Formatted display string (e.g., "httpGet in myFunction")
+ */
+export function formatErrorDisplay(errorMeta) {
+  if (errorMeta.origin) {
+    return `${errorMeta.method} in ${errorMeta.origin}`;
+  }
+  return errorMeta.method;
+}
+
+/**
+ * Get the specific HkPromise method that caused the error
+ * 
+ * @param {string[]} cleanedStack - Array of cleaned stack trace frames
+ * @returns {string|null} HkPromise method name or null
+ */
+export function getHkPromiseMethod(cleanedStack) {
+  const hkPromiseFrame = cleanedStack.find(frame => 
+    frame.includes('reject@') || 
+    frame.includes('tryReject@') || 
+    frame.includes('setTimeout@') || 
+    frame.includes('cancel@') || 
+    frame.includes('tryCancel@')
+  );
+  
+  if (!hkPromiseFrame) return null;
+  
+  if (hkPromiseFrame.includes('reject@')) return 'reject';
+  if (hkPromiseFrame.includes('tryReject@')) return 'tryReject';
+  if (hkPromiseFrame.includes('setTimeout@')) return 'setTimeout';
+  if (hkPromiseFrame.includes('cancel@')) return 'cancel';
+  if (hkPromiseFrame.includes('tryCancel@')) return 'tryCancel';
+  
+  return null;
+}
+
+/**
+ * Get the specific HTTP method that caused the error
+ * 
+ * @param {string[]} cleanedStack - Array of cleaned stack trace frames
+ * @returns {string|null} HTTP method name or null
+ */
+export function getHttpMethod(cleanedStack) {
+  const httpFrame = cleanedStack.find(frame => 
+    frame.includes('network/http/http-request.js')
+  );
+  
+  if (!httpFrame) return null;
+  
+  if (httpFrame.includes('httpGet@')) return 'httpGet';
+  if (httpFrame.includes('httpPost@')) return 'httpPost';
+  if (httpFrame.includes('httpPut@')) return 'httpPut';
+  if (httpFrame.includes('httpDelete@')) return 'httpDelete';
+  if (httpFrame.includes('httpPatch@')) return 'httpPatch';
+  if (httpFrame.includes('httpOptions@')) return 'httpOptions';
+  if (httpFrame.includes('httpRequest@')) return 'httpRequest';
+  
+  return null;
+}
+
+/**
+ * Extract user function name from stack trace
+ * 
+ * @param {Error} error - The error object
+ * @param {string[]} cleanedStack - Array of cleaned stack trace frames
+ * @returns {string|null} User function name or null
+ */
+export function extractUserFunctionName(error, cleanedStack) {
+  // Check if this is a LoggerError - look for the frame after Logger.error
+  if (error.name === 'LoggerError' && cleanedStack.length > 1) {
+    const loggerErrorIndex = cleanedStack.findIndex(frame => 
+      frame.includes('Logger.error') && frame.includes('logger/Logger.js')
+    );
+    if (loggerErrorIndex >= 0 && loggerErrorIndex + 1 < cleanedStack.length) {
+      return parseFunctionName(cleanedStack[loggerErrorIndex + 1]);
+    }
+  }
+
+  if (error.name === 'DetailedError' && cleanedStack.length > 1) {
+    // Check if this DetailedError was created by Logger.error - look for the frame after Logger.error
+    const loggerErrorIndex = cleanedStack.findIndex(frame => 
+      (frame.includes('Logger.error') && frame.includes('logger/Logger.js')) ||
+      (frame.includes('error@') && frame.includes('logger/Logger.js'))
+    );
+    if (loggerErrorIndex >= 0 && loggerErrorIndex + 1 < cleanedStack.length) {
+      return parseFunctionName(cleanedStack[loggerErrorIndex + 1]);
+    }
+    
+    // For rethrow errors, look for the frame after rethrow (handle both formats)
+    const rethrowIndex = cleanedStack.findIndex(frame => 
+      frame.includes('rethrow@') || frame.includes('at rethrow (')
+    );
+    if (rethrowIndex >= 0 && rethrowIndex + 1 < cleanedStack.length) {
+      return parseFunctionName(cleanedStack[rethrowIndex + 1]);
+    }
+  }
+
+  if (error.name === 'PromiseError' && cleanedStack.length > 1) {
+    // For PromiseError, look for the frame after HkPromise methods
+    const hkPromiseIndex = cleanedStack.findIndex(frame => 
+      frame.includes('reject@') || 
+      frame.includes('tryReject@') || 
+      frame.includes('setTimeout@') || 
+      frame.includes('cancel@') || 
+      frame.includes('tryCancel@')
+    );
+    if (hkPromiseIndex >= 0 && hkPromiseIndex + 1 < cleanedStack.length) {
+      return parseFunctionName(cleanedStack[hkPromiseIndex + 1]);
+    }
+  }
+
+  if (error.name === 'HttpError' && cleanedStack.length > 1) {
+    // For HttpError, find the last frame containing http-request.js, then take the next one
+    let lastHttpIndex = -1;
+    for (let i = 0; i < cleanedStack.length; i++) {
+      if (cleanedStack[i].includes('network/http/http-request.js')) {
+        lastHttpIndex = i;
+      }
+    }
+    if (lastHttpIndex >= 0 && lastHttpIndex + 1 < cleanedStack.length) {
+      return parseFunctionName(cleanedStack[lastHttpIndex + 1]);
+    }
+  }
+
+  if (error.name === 'ValiError' && cleanedStack.length > 1) {
+    // For validation errors, look for the frame after expect_ function first (handle Node.js format)
+    const expectIndex = cleanedStack.findIndex(frame => 
+      frame.includes('expect_') || frame.includes('Module.expect_')
+    );
+    if (expectIndex >= 0 && expectIndex + 1 < cleanedStack.length) {
+      return parseFunctionName(cleanedStack[expectIndex + 1]);
+    }
+    
+    // If no expect_ function, look for valibotParser wrapper
+    const valibotIndex = cleanedStack.findIndex(frame => frame.includes('valibotParser'));
+    if (valibotIndex >= 0 && valibotIndex + 1 < cleanedStack.length) {
+      return parseFunctionName(cleanedStack[valibotIndex + 1]);
+    }
+  }
+
+  // Find the first meaningful function name (skip anonymous functions and framework code)
+  for (let i = 0; i < cleanedStack.length; i++) {
+    const functionName = parseFunctionName(cleanedStack[i]);
+    if (functionName && isMeaningfulFunctionName(functionName)) {
+      return functionName;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if function name is meaningful (not anonymous or framework code)
+ * 
+ * @param {string} functionName - Function name to check
+ * @returns {boolean} True if the function name is meaningful
+ */
+export function isMeaningfulFunctionName(functionName) {
+  // Skip empty names, anonymous functions, and framework/internal functions
+  if (!functionName || 
+      functionName === '' || 
+      functionName.includes('<') || 
+      functionName.includes('/') ||
+      functionName.startsWith('async ') ||
+      functionName === 'async' ||
+      functionName === 'Promise' ||
+      functionName === 'new Promise' ||
+      functionName.includes('internal') ||
+      functionName.includes('node_modules')) {
+    return false;
+  }
+  
+  return true;
+}
+
+/**
+ * Parse function name from stack frame
+ * 
+ * @param {string} frame - Stack trace frame
+ * @returns {string|null} Function name or null
+ */
+export function parseFunctionName(frame) {
+  // Handle both Firefox format: "functionName@file:line:col"
+  // and Node.js format: "at functionName (file:line:col)" or "at Module.functionName (file:line:col)"
+  
+  // Firefox format
+  const firefoxMatch = frame.match(/^([^@]+)@/);
+  if (firefoxMatch) {
+    return firefoxMatch[1];
+  }
+  
+  // Node.js format
+  const nodeMatch = frame.match(/^\s*at\s+(?:Module\.)?([^\s(]+)/);
+  if (nodeMatch) {
+    return nodeMatch[1];
+  }
+  
+  return null;
+}

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

@@ -1,10 +1,16 @@
 /**
  * Pino adapter for server-side logging
  */
-
 import pino from 'pino';
 import { dev } from '$app/environment';
 
+import {
+  detectErrorMeta,
+  findRelevantFrameIndex,
+  formatErrorDisplay,
+  parseFunctionName
+} from './formatting.js';
+
 /**
  * Pino adapter that bridges Logger events to pino
  */
@@ -21,27 +27,94 @@ export class PinoAdapter {
     this.#projectRoot = import.meta.env.VITE_PROJECT_ROOT || process.cwd();
     const baseOptions = {
       serializers: {
-        err: (err) => {
+        errors: (err) => {
+
+          /** @type {import('./typedef').ErrorSummary[]} */
           const chain = [];
+          let loggedAt = null;
+
           let current = err;
           let isFirst = true;
 
-          while (current) {
+          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);
+                const cleanedStackArray = cleanedStackString
+                  .split('\n')
+                  .map((line) => line.trim())
+                  .filter(
+                    (line) =>
+                      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'))
+                );
+
+                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 "
+                }
+              }
+
+              // Skip the LoggerError and move to the actual error
+              current = current.cause;
+              isFirst = false;
+              continue;
+            }
             /** @type {import('./typedef').ErrorSummary} */
             const serialized = {
               name: current.name,
-              message: current.message,
-              ...(isFirst && {
-                stack: this.#cleanStackTrace(current.stack)
-              })
+              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')
+                .map((line) => line.trim())
+                .filter(
+                  (line) =>
+                    line && line !== current.name + ': ' + current.message
+                );
+
+              const errorMeta = detectErrorMeta(current, cleanedStackArray);
+              const relevantFrameIndex = findRelevantFrameIndex(
+                current,
+                cleanedStackArray
+              );
+
+              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
-            if (current.status !== undefined) {
-              serialized.status = current.status;
+            const httpError = /** @type {import('../../../network/errors.js').HttpError} */ (current);
+            if (httpError.status !== undefined) {
+              serialized.status = httpError.status;
             }
-            if (current.details !== undefined) {
-              serialized.details = current.details;
+            if (httpError.details !== undefined) {
+              serialized.details = httpError.details;
             }
 
             chain.push(serialized);
@@ -49,19 +122,20 @@ export class PinoAdapter {
             isFirst = false;
           }
 
-          return { errorChain: chain };
+          return loggedAt ? { chain, loggedAt } : chain;
         }
       }
     };
 
     // Add error handling for missing pino-pretty in dev
-    if (dev) {
+    if ( dev) {
       const devOptions = {
         level: 'debug',
         transport: {
           target: 'pino-pretty',
           options: {
-            colorize: true
+            colorize: true,
+            ignore: 'hostname,pid'
           }
         }
       };
@@ -69,7 +143,10 @@ export class PinoAdapter {
       try {
         this.pino = pino({ ...baseOptions, ...devOptions, ...options });
       } catch (error) {
-        if (error.message.includes('pino-pretty')) {
+        if (
+          error.message.includes('Cannot find module') &&
+          error.message.includes('pino-pretty')
+        ) {
           const errorMessage = `
 ╭─────────────────────────────────────────────────────────────╮
 │                     Missing Dependency                      │
@@ -101,16 +178,23 @@ export class PinoAdapter {
     let cleaned = stack;
 
     // Escape special regex characters in the project root path
-    const escapedRoot = this.#projectRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    
+    const escapedRoot = this.#projectRoot.replace(
+      /[.*+?^${}()|[\]\\]/g,
+      '\\$&'
+    );
+
     // Replace project root path with relative path, handling file:// protocol
     // Match both regular paths and file:// URLs
-    const rootRegex = new RegExp(`(\\s+at\\s+.*\\()(file://)?${escapedRoot}[\\/\\\\]`, 'g');
+    const rootRegex = new RegExp(
+      `(\\s+at\\s+.*\\()(file://)?${escapedRoot}[\\/\\\\]`,
+      'g'
+    );
     cleaned = cleaned.replace(rootRegex, '$1');
 
     // 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
@@ -137,11 +221,12 @@ export class PinoAdapter {
     if (details) {
       if (details instanceof Error) {
         // details is directly an error
-        logData.err = details;
+        logData.errors = details;
       } else if (details.error instanceof Error) {
         // details has an error property
-        logData.err = details.error;
+        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;
@@ -152,6 +237,12 @@ export class PinoAdapter {
       }
     }
 
+    // Check if we have loggedAt info from the serializer
+    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);
   }
 

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

@@ -1,5 +1,23 @@
 declare const _default: {};
 export default _default;
+export type ErrorSummaryMeta = {
+    /**
+     * - Error category (rethrow, validation, http, promise, error)
+     */
+    category: string;
+    /**
+     * - Specific method (rethrow, expect, httpGet, hkpromise.timeout, etc)
+     */
+    method: string;
+    /**
+     * - User function name where error originated
+     */
+    origin?: string;
+    /**
+     * - Index of most relevant stack frame to highlight
+     */
+    relevantFrameIndex?: number;
+};
 export type ErrorSummary = {
     /**
      * - The name of the exception/error
@@ -9,6 +27,10 @@ export type ErrorSummary = {
      * - The error message
      */
     message: string;
+    /**
+     * - Error meta
+     */
+    meta?: ErrorSummaryMeta;
     /**
      * Stack trace (in debug mode for first exception)
      */
@@ -21,4 +43,12 @@ export type ErrorSummary = {
      * - Additional error details (for HttpError instances)
      */
     details?: any;
+    /**
+     * - Formatted error type for display
+     */
+    errorType?: string;
+    /**
+     * - Cleaned stack frames for terminal display
+     */
+    stackFrames?: string[];
 };

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 {};