@visulima/pail 4.0.0-alpha.9 → 4.0.1

package/dist/error.d.ts

@@ -1,104 +1,103 @@
 /**
- * Options for creating a PailError.
- *
- * Extends standard error properties with self-documenting fields
- * that provide actionable context for debugging, particularly useful
- * for AI-assisted log analysis.
- */
+* Options for creating a PailError.
+*
+* Extends standard error properties with self-documenting fields
+* that provide actionable context for debugging, particularly useful
+* for AI-assisted log analysis.
+*/
 interface PailErrorOptions {
-    /** The root cause of this error */
-    cause?: unknown;
-    /** A suggested resolution or steps to fix the issue */
-    fix?: string;
-    /** A link to relevant documentation or issue tracker */
-    link?: string;
-    /** The error message */
-    message: string;
-    /** HTTP status code associated with this error */
-    status?: number;
-    /** An explanation of what caused the failure */
-    why?: string;
+  /** The root cause of this error */
+  cause?: unknown;
+  /** A suggested resolution or steps to fix the issue */
+  fix?: string;
+  /** A link to relevant documentation or issue tracker */
+  link?: string;
+  /** The error message */
+  message: string;
+  /** HTTP status code associated with this error */
+  status?: number;
+  /** An explanation of what caused the failure */
+  why?: string;
 }
 /**
- * Self-documenting error class for structured logging.
- *
- * Inspired by evlog's structured error approach, PailError extends the native
- * Error class with additional fields that make log entries immediately actionable:
- * - `why`: Explains what caused the failure
- * - `fix`: Suggests how to resolve the issue
- * - `link`: Points to relevant documentation
- * - `status`: HTTP status code for request-related errors
- *
- * These fields are preserved through the logging pipeline and displayed by reporters,
- * making it easier for both humans and AI agents to understand and resolve issues.
- * @example
- * ```typescript
- * import { PailError, createPailError } from "@visulima/pail/error";
- *
- * // Using the class directly
- * throw new PailError({
- *   message: "Payment processing failed",
- *   status: 402,
- *   why: "The customer's card was declined by the payment provider",
- *   fix: "Retry with a different payment method or contact the card issuer",
- *   link: "https://docs.example.com/payments/declined",
- * });
- *
- * // Using the factory function
- * throw createPailError("Connection timeout");
- *
- * // With full options
- * throw createPailError({
- *   message: "Database connection failed",
- *   why: "Connection pool exhausted after 30s timeout",
- *   fix: "Increase pool size or check for connection leaks",
- * });
- * ```
- */
+* Self-documenting error class for structured logging.
+*
+* Inspired by evlog's structured error approach, PailError extends the native
+* Error class with additional fields that make log entries immediately actionable:
+* - `why`: Explains what caused the failure
+* - `fix`: Suggests how to resolve the issue
+* - `link`: Points to relevant documentation
+* - `status`: HTTP status code for request-related errors
+*
+* These fields are preserved through the logging pipeline and displayed by reporters,
+* making it easier for both humans and AI agents to understand and resolve issues.
+* @example
+* ```typescript
+* import { PailError, createPailError } from "@visulima/pail/error";
+*
+* // Using the class directly
+* throw new PailError({
+*   message: "Payment processing failed",
+*   status: 402,
+*   why: "The customer's card was declined by the payment provider",
+*   fix: "Retry with a different payment method or contact the card issuer",
+*   link: "https://docs.example.com/payments/declined",
+* });
+*
+* // Using the factory function
+* throw createPailError("Connection timeout");
+*
+* // With full options
+* throw createPailError({
+*   message: "Database connection failed",
+*   why: "Connection pool exhausted after 30s timeout",
+*   fix: "Increase pool size or check for connection leaks",
+* });
+* ```
+*/
 declare class PailError extends Error {
-    /** HTTP status code (defaults to 500) */
-    readonly status: number;
-    /** Explanation of what caused the failure */
-    readonly why: string | undefined;
-    /** Suggested resolution steps */
-    readonly fix: string | undefined;
-    /** Link to relevant documentation */
-    readonly link: string | undefined;
-    constructor(options: PailErrorOptions | string);
-    /**
-     * Converts the error to a JSON-serializable object.
-     *
-     * Includes all self-documenting fields in the output for structured logging.
-     * @returns A plain object representation of the error
-     */
-    toJSON(): Record<string, unknown>;
-    /**
-     * Returns a formatted string representation including self-documenting fields.
-     * @returns Formatted error string with why/fix/link context
-     */
-    toString(): string;
+  /** HTTP status code (defaults to 500) */
+  readonly status: number;
+  /** Explanation of what caused the failure */
+  readonly why: string | undefined;
+  /** Suggested resolution steps */
+  readonly fix: string | undefined;
+  /** Link to relevant documentation */
+  readonly link: string | undefined;
+  constructor(options: PailErrorOptions | string);
+  /**
+  * Converts the error to a JSON-serializable object.
+  *
+  * Includes all self-documenting fields in the output for structured logging.
+  * @returns A plain object representation of the error
+  */
+  toJSON(): Record<string, unknown>;
+  /**
+  * Returns a formatted string representation including self-documenting fields.
+  * @returns Formatted error string with why/fix/link context
+  */
+  override toString(): string;
 }
 /**
- * Factory function for creating PailError instances.
- *
- * A convenient shorthand for creating PailError objects. Accepts either
- * a string message or a full PailErrorOptions object.
- * @param options Error message string or PailErrorOptions object
- * @returns A new PailError instance
- * @example
- * ```typescript
- * import { createPailError } from "@visulima/pail/error";
- *
- * throw createPailError("Something went wrong");
- *
- * throw createPailError({
- *   message: "Auth failed",
- *   status: 401,
- *   why: "Token expired",
- *   fix: "Refresh the authentication token",
- * });
- * ```
- */
+* Factory function for creating PailError instances.
+*
+* A convenient shorthand for creating PailError objects. Accepts either
+* a string message or a full PailErrorOptions object.
+* @param options Error message string or PailErrorOptions object
+* @returns A new PailError instance
+* @example
+* ```typescript
+* import { createPailError } from "@visulima/pail/error";
+*
+* throw createPailError("Something went wrong");
+*
+* throw createPailError({
+*   message: "Auth failed",
+*   status: 401,
+*   why: "Token expired",
+*   fix: "Refresh the authentication token",
+* });
+* ```
+*/
 declare const createPailError: (options: PailErrorOptions | string) => PailError;
-export { createPailError, PailError };
-export type { PailErrorOptions };
+export { PailError, type PailErrorOptions, createPailError };

package/dist/error.js

@@ -1,76 +1,5 @@
-class PailError extends Error {
-  /** HTTP status code (defaults to 500) */
-  status;
-  /** Explanation of what caused the failure */
-  why;
-  /** Suggested resolution steps */
-  fix;
-  /** Link to relevant documentation */
-  link;
-  constructor(options) {
-    const resolvedOptions = typeof options === "string" ? { message: options } : options;
-    super(resolvedOptions.message, resolvedOptions.cause === void 0 ? void 0 : { cause: resolvedOptions.cause });
-    this.name = "PailError";
-    this.status = resolvedOptions.status ?? 500;
-    this.why = resolvedOptions.why;
-    this.fix = resolvedOptions.fix;
-    this.link = resolvedOptions.link;
-  }
-  /**
-   * Converts the error to a JSON-serializable object.
-   *
-   * Includes all self-documenting fields in the output for structured logging.
-   * @returns A plain object representation of the error
-   */
-  toJSON() {
-    const json = {
-      message: this.message,
-      name: this.name,
-      status: this.status
-    };
-    if (this.why) {
-      json.why = this.why;
-    }
-    if (this.fix) {
-      json.fix = this.fix;
-    }
-    if (this.link) {
-      json.link = this.link;
-    }
-    if (this.stack) {
-      json.stack = this.stack;
-    }
-    if (this.cause !== void 0) {
-      json.cause = this.cause instanceof Error ? { message: this.cause.message, name: this.cause.name, stack: this.cause.stack } : this.cause;
-    }
-    return json;
-  }
-  /**
-   * Returns a formatted string representation including self-documenting fields.
-   * @returns Formatted error string with why/fix/link context
-   */
-  toString() {
-    let output = `${this.name} [${this.status}]: ${this.message}`;
-    if (this.why) {
-      output += `
-  Why: ${this.why}`;
-    }
-    if (this.fix) {
-      output += `
-  Fix: ${this.fix}`;
-    }
-    if (this.link) {
-      output += `
-  Link: ${this.link}`;
-    }
-    if (this.cause !== void 0) {
-      const causeMessage = this.cause instanceof Error ? this.cause.message : String(this.cause);
-      output += `
-  Cause: ${causeMessage}`;
-    }
-    return output;
-  }
-}
-const createPailError = (options) => new PailError(options);
-
-export { PailError, createPailError };
+class e extends Error{status;why;fix;link;constructor(s){const t=typeof s=="string"?{message:s}:s;super(t.message,t.cause===void 0?void 0:{cause:t.cause}),this.name="PailError",this.status=t.status??500,this.why=t.why,this.fix=t.fix,this.link=t.link}toJSON(){const s={message:this.message,name:this.name,status:this.status};return this.why&&(s.why=this.why),this.fix&&(s.fix=this.fix),this.link&&(s.link=this.link),this.stack&&(s.stack=this.stack),this.cause!==void 0&&(s.cause=this.cause instanceof Error?{message:this.cause.message,name:this.cause.name,stack:this.cause.stack}:this.cause),s}toString(){let s=`${this.name} [${String(this.status)}]: ${this.message}`;if(this.why&&(s+=`
+  Why: ${this.why}`),this.fix&&(s+=`
+  Fix: ${this.fix}`),this.link&&(s+=`
+  Link: ${this.link}`),this.cause!==void 0){const t=this.cause instanceof Error?this.cause.message:String(this.cause);s+=`
+  Cause: ${t}`}return s}}const a=i=>new e(i);export{e as PailError,a as createPailError};