@bombillazo/error-x 0.4.0 → 0.4.2

package/README.md

@@ -36,7 +36,6 @@ yarn add @bombillazo/error-x
 
 This library uses modern JavaScript features and ES2022 APIs. For browser compatibility, ensure your build tool (e.g., Vite, webpack, esbuild) is configured to target ES2022 or transpile accordingly.
 
-
 > [!WARNING]
 >
 > This library is currently in pre-v1.0 development. While we strive to minimize breaking changes, the API may evolve based on feedback and real-world usage. We recommend pinning to specific versions and reviewing release notes when updating.
@@ -87,7 +86,7 @@ try {
 ### Constructor
 
 ```typescript
-new ErrorX(message?: string | ErrorXOptions)
+new ErrorX(input?: string | ErrorXOptions)
 ```
 
 All parameters are optional. ErrorX uses sensible defaults:
@@ -149,6 +148,7 @@ All presets use **camelCase naming** and include:
 - `type`: Set to `'http'` for all HTTP presets
 
 **4xx Client Errors:**
+
 `badRequest`, `unauthorized`, `paymentRequired`, `forbidden`, `notFound`, `methodNotAllowed`, `notAcceptable`, `proxyAuthenticationRequired`, `requestTimeout`, `conflict`, `gone`, `lengthRequired`, `preconditionFailed`, `payloadTooLarge`, `uriTooLong`, `unsupportedMediaType`, `rangeNotSatisfiable`, `expectationFailed`, `imATeapot`, `unprocessableEntity`, `locked`, `failedDependency`, `tooEarly`, `upgradeRequired`, `preconditionRequired`, `tooManyRequests`, `requestHeaderFieldsTooLarge`, `unavailableForLegalReasons`
 
 **5xx Server Errors:**
@@ -281,14 +281,19 @@ const enriched = error.withMetadata({ b: 2 })
 // enriched.metadata = { a: 1, b: 2 }
 ```
 
-#### `cleanStackTrace(delimiter?: string): ErrorX`
+#### `ErrorX.cleanStack(stack?: string, delimiter?: string): string`
 
-Removes stack trace lines before a delimiter:
+Cleans a stack trace by removing ErrorX internal calls and optionally trimming after a delimiter:
 
 ```typescript
 const error = new ErrorX('test')
-const cleaned = error.cleanStackTrace('my-app-boundary')
-// Stack trace only includes lines after 'my-app-boundary'
+
+// 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-boundary')
+// Returns stack trace starting after the line containing 'my-app-boundary'
 ```
 
 #### `toJSON(): ErrorXSerialized`

package/dist/index.cjs

@@ -46,6 +46,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.
    *
@@ -89,15 +91,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;
@@ -117,8 +113,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);
@@ -133,6 +129,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.
@@ -147,7 +181,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
    * })
    * ```
    */
@@ -161,6 +196,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)
    *
@@ -234,27 +282,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;
@@ -278,30 +337,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.
@@ -466,43 +510,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.
@@ -590,34 +597,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;
   }
@@ -653,7 +633,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;
@@ -663,19 +644,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;
   }
 };