@bombillazo/error-x 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -60,8 +60,8 @@ type ErrorXOptions<TMetadata extends ErrorXMetadata = ErrorXMetadata> = {
     code?: string | number;
     /** User-friendly message for UI display */
     uiMessage?: string | undefined;
-    /** Original error that caused this error (preserves error chain) */
-    cause?: Error | unknown;
+    /** Original error that caused this error (preserves error chain, will be converted to ErrorXCause format) */
+    cause?: ErrorXCause | Error | unknown;
     /** Additional context and debugging information */
     metadata?: TMetadata | undefined;
     /** HTTP status code (100-599) for HTTP-related errors */
@@ -164,6 +164,11 @@ interface ErrorXConfig {
      * - string[]: Custom patterns to match and remove from stack traces
      */
     cleanStack?: boolean | string[];
+    /**
+     * Delimiter to trim stack traces after a specified line
+     * When set, stack traces will be trimmed to start after the first line containing this string
+     */
+    cleanStackDelimiter?: string;
 }
 /**
  * Enhanced Error class with rich metadata, type-safe error handling, and intelligent error conversion.
@@ -177,7 +182,8 @@ interface ErrorXConfig {
  *   docsMap: {
  *     'AUTH_FAILED': 'errors/authentication',
  *     'DB_ERROR': 'errors/database'
- *   }
+ *   },
+ *   cleanStackDelimiter: 'my-app-entry' // Clean stack traces after this line
  * })
  *
  * // Basic usage
@@ -224,6 +230,8 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
     docsUrl: string | undefined;
     /** Where the error originated (service name, module, component) */
     source: string | undefined;
+    /** Original error that caused this error (preserves error chain) */
+    cause: ErrorXCause | undefined;
     /**
      * Creates a new ErrorX instance with enhanced error handling capabilities.
      *
@@ -264,6 +272,12 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      * @returns Default error name 'Error'
      */
     private static getDefaultName;
+    /**
+     * Converts any value to ErrorXCause format.
+     * @param value - Value to convert to ErrorXCause
+     * @returns ErrorXCause object or undefined if value is null/undefined
+     */
+    private static toErrorXCause;
     /**
      * Configure global ErrorX settings.
      * This method allows you to set defaults for all ErrorX instances.
@@ -278,7 +292,8 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      *   docsMap: {
      *     'AUTH_FAILED': 'authentication-errors',
      *     'DB_ERROR': 'database-errors'
-     *   }
+     *   },
+     *   cleanStackDelimiter: 'app-entry-point' // Trim stack traces after this line
      * })
      * ```
      */
@@ -288,6 +303,17 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      * Returns null if no configuration has been set.
      */
     static getConfig(): ErrorXConfig | null;
+    /**
+     * Reset global configuration to null.
+     * Useful for testing or when you want to clear all configuration.
+     *
+     * @example
+     * ```typescript
+     * ErrorX.resetConfig()
+     * const config = ErrorX.getConfig() // null
+     * ```
+     */
+    static resetConfig(): void;
     /**
      * Validates HTTP status code to ensure it's within valid range (100-599)
      *
@@ -327,36 +353,32 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
     private static generateDefaultCode;
     /**
      * Preserves the original error's stack trace while updating the error message.
-     * Combines the new error's message with the original error's stack trace.
+     * Combines the new error's message with the original error's stack trace from ErrorXCause.
      *
-     * @param originalError - The original error whose stack to preserve
+     * @param cause - The ErrorXCause containing the original stack to preserve
      * @param newError - The new error whose message to use
      * @returns Combined stack trace with new error message and original stack
      */
-    private static preserveOriginalStack;
+    private static preserveOriginalStackFromCause;
     /**
-     * Cleans the stack trace by removing ErrorX internal method calls.
+     * Cleans a stack trace by removing ErrorX internal method calls and optionally trimming after a delimiter.
      * This provides cleaner stack traces that focus on user code.
      *
-     * @param stack - Raw stack trace to clean
-     * @returns Cleaned stack trace without ErrorX internal calls
-     */
-    private static cleanStack;
-    /**
-     * Processes an error's stack trace to trim it after a specified delimiter.
-     * Useful for removing irrelevant stack frames before a specific function.
-     *
-     * @param error - Error whose stack to process
-     * @param delimiter - String to search for in stack lines
-     * @returns Processed stack trace starting after the delimiter
+     * @param stack - Raw stack trace string to clean
+     * @param delimiter - Optional delimiter to trim stack trace after (overrides config delimiter)
+     * @returns Cleaned stack trace without internal calls and optionally trimmed after delimiter
      *
      * @example
      * ```typescript
-     * const processed = ErrorX.processErrorStack(error, 'my-app-entry')
+     * // Clean with pattern-based removal only
+     * const cleaned = ErrorX.cleanStack(error.stack)
+     *
+     * // Clean and trim after delimiter
+     * const trimmed = ErrorX.cleanStack(error.stack, 'my-app-entry')
      * // Returns stack trace starting after the line containing 'my-app-entry'
      * ```
      */
-    private static processErrorStack;
+    static cleanStack(stack?: string, delimiter?: string): string;
     /**
      * Creates a new ErrorX instance with additional metadata merged with existing metadata.
      * The original error properties are preserved while extending the metadata.
@@ -436,21 +458,6 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
     static from(error: Error): ErrorX;
     static from(error: string): ErrorX;
     static from(error: unknown): ErrorX;
-    /**
-     * Creates a new ErrorX instance with cleaned stack trace using the specified delimiter.
-     * Returns the same instance if no delimiter is provided or no stack is available.
-     *
-     * @param delimiter - Optional string to search for in stack lines
-     * @returns New ErrorX instance with cleaned stack trace, or the same instance if no cleaning needed
-     *
-     * @example
-     * ```typescript
-     * const error = new ErrorX({ message: 'Database error' })
-     * const cleanedError = error.cleanStackTrace('database-layer')
-     * // Returns new ErrorX with stack trace starting after 'database-layer'
-     * ```
-     */
-    cleanStackTrace(delimiter?: string): ErrorX<TMetadata>;
     /**
      * Converts the ErrorX instance to a detailed string representation.
      * Includes error name, message, code, timestamp, metadata, and stack trace.

package/dist/index.js

@@ -40,6 +40,8 @@ var ErrorX = class _ErrorX extends Error {
   docsUrl;
   /** Where the error originated (service name, module, component) */
   source;
+  /** Original error that caused this error (preserves error chain) */
+  cause;
   /**
    * Creates a new ErrorX instance with enhanced error handling capabilities.
    *
@@ -83,15 +85,9 @@ var ErrorX = class _ErrorX extends Error {
     }
     const envConfig = _ErrorX.getConfig();
     const message = options.message?.trim() ? options.message : "An error occurred";
-    super(message, { cause: options.cause });
-    if (options.cause !== void 0 && !Object.hasOwn(this, "cause")) {
-      Object.defineProperty(this, "cause", {
-        value: options.cause,
-        writable: true,
-        enumerable: false,
-        configurable: true
-      });
-    }
+    const convertedCause = _ErrorX.toErrorXCause(options.cause);
+    super(message);
+    this.cause = convertedCause;
     this.name = options.name ?? _ErrorX.getDefaultName();
     this.code = options.code != null ? String(options.code) : _ErrorX.generateDefaultCode(options.name);
     this.uiMessage = options.uiMessage;
@@ -111,8 +107,8 @@ var ErrorX = class _ErrorX extends Error {
       }
     }
     this.docsUrl = options.docsUrl ?? generatedDocsUrl;
-    if (options.cause instanceof Error) {
-      this.stack = _ErrorX.preserveOriginalStack(options.cause, this);
+    if (convertedCause?.stack) {
+      this.stack = _ErrorX.preserveOriginalStackFromCause(convertedCause, this);
     } else {
       if (typeof Error.captureStackTrace === "function") {
         Error.captureStackTrace(this, this.constructor);
@@ -127,6 +123,44 @@ var ErrorX = class _ErrorX extends Error {
   static getDefaultName() {
     return "Error";
   }
+  /**
+   * Converts any value to ErrorXCause format.
+   * @param value - Value to convert to ErrorXCause
+   * @returns ErrorXCause object or undefined if value is null/undefined
+   */
+  static toErrorXCause(value) {
+    if (value === void 0 || value === null) {
+      return void 0;
+    }
+    if (value instanceof Error) {
+      const cause = {
+        message: value.message
+      };
+      if (value.name) {
+        cause.name = value.name;
+      }
+      if (value.stack) {
+        cause.stack = value.stack;
+      }
+      return cause;
+    }
+    if (typeof value === "object") {
+      const obj = value;
+      const cause = {
+        message: String(obj.message || obj)
+      };
+      if (obj.name) {
+        cause.name = String(obj.name);
+      }
+      if (obj.stack) {
+        cause.stack = String(obj.stack);
+      }
+      return cause;
+    }
+    return {
+      message: String(value)
+    };
+  }
   /**
    * Configure global ErrorX settings.
    * This method allows you to set defaults for all ErrorX instances.
@@ -141,7 +175,8 @@ var ErrorX = class _ErrorX extends Error {
    *   docsMap: {
    *     'AUTH_FAILED': 'authentication-errors',
    *     'DB_ERROR': 'database-errors'
-   *   }
+   *   },
+   *   cleanStackDelimiter: 'app-entry-point' // Trim stack traces after this line
    * })
    * ```
    */
@@ -155,6 +190,19 @@ var ErrorX = class _ErrorX extends Error {
   static getConfig() {
     return _ErrorX._config;
   }
+  /**
+   * Reset global configuration to null.
+   * Useful for testing or when you want to clear all configuration.
+   *
+   * @example
+   * ```typescript
+   * ErrorX.resetConfig()
+   * const config = ErrorX.getConfig() // null
+   * ```
+   */
+  static resetConfig() {
+    _ErrorX._config = null;
+  }
   /**
    * Validates HTTP status code to ensure it's within valid range (100-599)
    *
@@ -228,27 +276,38 @@ var ErrorX = class _ErrorX extends Error {
   }
   /**
    * Preserves the original error's stack trace while updating the error message.
-   * Combines the new error's message with the original error's stack trace.
+   * Combines the new error's message with the original error's stack trace from ErrorXCause.
    *
-   * @param originalError - The original error whose stack to preserve
+   * @param cause - The ErrorXCause containing the original stack to preserve
    * @param newError - The new error whose message to use
    * @returns Combined stack trace with new error message and original stack
    */
-  static preserveOriginalStack(originalError, newError) {
-    if (!originalError.stack) return newError.stack || "";
+  static preserveOriginalStackFromCause(cause, newError) {
+    if (!cause.stack) return newError.stack || "";
     const newErrorFirstLine = `${newError.name}: ${newError.message}`;
-    const originalStackLines = originalError.stack.split("\n");
+    const originalStackLines = cause.stack.split("\n");
     const originalStackTrace = originalStackLines.slice(1);
     return [newErrorFirstLine, ...originalStackTrace].join("\n");
   }
   /**
-   * Cleans the stack trace by removing ErrorX internal method calls.
+   * Cleans a stack trace by removing ErrorX internal method calls and optionally trimming after a delimiter.
    * This provides cleaner stack traces that focus on user code.
    *
-   * @param stack - Raw stack trace to clean
-   * @returns Cleaned stack trace without ErrorX internal calls
+   * @param stack - Raw stack trace string to clean
+   * @param delimiter - Optional delimiter to trim stack trace after (overrides config delimiter)
+   * @returns Cleaned stack trace without internal calls and optionally trimmed after delimiter
+   *
+   * @example
+   * ```typescript
+   * // Clean with pattern-based removal only
+   * const cleaned = ErrorX.cleanStack(error.stack)
+   *
+   * // Clean and trim after delimiter
+   * const trimmed = ErrorX.cleanStack(error.stack, 'my-app-entry')
+   * // Returns stack trace starting after the line containing 'my-app-entry'
+   * ```
    */
-  static cleanStack(stack) {
+  static cleanStack(stack, delimiter) {
     if (!stack) return "";
     const config = _ErrorX.getConfig();
     const cleanStackConfig = config?.cleanStack ?? true;
@@ -272,30 +331,15 @@ var ErrorX = class _ErrorX extends Error {
       }
       cleanedLines.push(line);
     }
-    return cleanedLines.join("\n");
-  }
-  /**
-   * Processes an error's stack trace to trim it after a specified delimiter.
-   * Useful for removing irrelevant stack frames before a specific function.
-   *
-   * @param error - Error whose stack to process
-   * @param delimiter - String to search for in stack lines
-   * @returns Processed stack trace starting after the delimiter
-   *
-   * @example
-   * ```typescript
-   * const processed = ErrorX.processErrorStack(error, 'my-app-entry')
-   * // Returns stack trace starting after the line containing 'my-app-entry'
-   * ```
-   */
-  static processErrorStack(error, delimiter) {
-    let stack = error.stack ?? "";
-    const stackLines = stack.split("\n");
-    const delimiterIndex = stackLines.findIndex((line) => line.includes(delimiter));
-    if (delimiterIndex !== -1) {
-      stack = stackLines.slice(delimiterIndex + 1).join("\n");
+    let cleanedStack = cleanedLines.join("\n");
+    const activeDelimiter = delimiter ?? config?.cleanStackDelimiter;
+    if (activeDelimiter) {
+      const delimiterIndex = cleanedLines.findIndex((line) => line.includes(activeDelimiter));
+      if (delimiterIndex !== -1) {
+        cleanedStack = cleanedLines.slice(delimiterIndex + 1).join("\n");
+      }
     }
-    return stack;
+    return cleanedStack;
   }
   /**
    * Creates a new ErrorX instance with additional metadata merged with existing metadata.
@@ -460,43 +504,6 @@ var ErrorX = class _ErrorX extends Error {
     const options = _ErrorX.convertUnknownToOptions(error);
     return new _ErrorX(options);
   }
-  /**
-   * Creates a new ErrorX instance with cleaned stack trace using the specified delimiter.
-   * Returns the same instance if no delimiter is provided or no stack is available.
-   *
-   * @param delimiter - Optional string to search for in stack lines
-   * @returns New ErrorX instance with cleaned stack trace, or the same instance if no cleaning needed
-   *
-   * @example
-   * ```typescript
-   * const error = new ErrorX({ message: 'Database error' })
-   * const cleanedError = error.cleanStackTrace('database-layer')
-   * // Returns new ErrorX with stack trace starting after 'database-layer'
-   * ```
-   */
-  cleanStackTrace(delimiter) {
-    if (delimiter && this.stack) {
-      const options = {
-        message: this.message,
-        name: this.name,
-        code: this.code,
-        uiMessage: this.uiMessage,
-        cause: this.cause,
-        httpStatus: this.httpStatus,
-        type: this.type,
-        sourceUrl: this.sourceUrl,
-        docsUrl: this.docsUrl,
-        source: this.source
-      };
-      if (this.metadata !== void 0) {
-        options.metadata = this.metadata;
-      }
-      const newError = new _ErrorX(options);
-      newError.stack = _ErrorX.processErrorStack(this, delimiter);
-      return newError;
-    }
-    return this;
-  }
   /**
    * Converts the ErrorX instance to a detailed string representation.
    * Includes error name, message, code, timestamp, metadata, and stack trace.
@@ -584,34 +591,7 @@ ${this.stack}`;
       serialized.stack = this.stack;
     }
     if (this.cause) {
-      if (this.cause instanceof Error) {
-        const cause = {
-          message: this.cause.message
-        };
-        if (this.cause.name) {
-          cause.name = this.cause.name;
-        }
-        if (this.cause.stack) {
-          cause.stack = this.cause.stack;
-        }
-        serialized.cause = cause;
-      } else if (typeof this.cause === "object" && this.cause !== null) {
-        const causeObj = this.cause;
-        const cause = {
-          message: String(causeObj.message || causeObj)
-        };
-        if (causeObj.name) {
-          cause.name = String(causeObj.name);
-        }
-        if (causeObj.stack) {
-          cause.stack = String(causeObj.stack);
-        }
-        serialized.cause = cause;
-      } else {
-        serialized.cause = {
-          message: String(this.cause)
-        };
-      }
+      serialized.cause = this.cause;
     }
     return serialized;
   }
@@ -647,7 +627,8 @@ ${this.stack}`;
       type: serialized.type,
       sourceUrl: serialized.sourceUrl,
       docsUrl: serialized.docsUrl,
-      source: serialized.source
+      source: serialized.source,
+      cause: serialized.cause
     };
     if (serialized.metadata !== void 0) {
       options.metadata = serialized.metadata;
@@ -657,19 +638,6 @@ ${this.stack}`;
       error.stack = serialized.stack;
     }
     error.timestamp = new Date(serialized.timestamp);
-    if (serialized.cause) {
-      const causeError = new Error(serialized.cause.message);
-      if (serialized.cause.name) {
-        causeError.name = serialized.cause.name;
-      }
-      if (serialized.cause.stack) {
-        causeError.stack = serialized.cause.stack;
-      }
-      Object.defineProperty(error, "cause", {
-        value: causeError,
-        writable: true
-      });
-    }
     return error;
   }
 };