@visulima/pail 4.0.0-alpha.10 → 4.0.0-alpha.12

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