@bombillazo/error-x 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -2,167 +2,22 @@
  * Metadata object containing additional context information for an error.
  * Can store any key-value pairs to provide extra debugging or business context.
  *
- * @example
+ * Users can use metadata to store application-specific behavior instructions if needed:
  * ```typescript
- * const metadata: ErrorMetadata = {
+ * const metadata = {
  *   userId: 123,
  *   operation: 'fetchUser',
- *   retryCount: 3
- * }
- * ```
- *
- * @public
- */
-type ErrorMetadata = Record<string, any>;
-/**
- * Predefined display targets for error notifications and UI feedback.
- * These enum values provide consistent, type-safe options for where errors should be displayed.
- *
- * @public
- */
-declare enum HandlingTargets {
-    MODAL = "modal",
-    TOAST = "toast",
-    INLINE = "inline",
-    BANNER = "banner",
-    CONSOLE = "console",
-    LOGGER = "logger",
-    NOTIFICATION = "notification"
-}
-/**
- * Display target type that allows both predefined enum values and custom strings.
- * This enables flexibility for custom UI components while providing standard options.
- *
- * @example
- * ```typescript
- * // Using predefined enum values
- * targets: [HandlingTargets.MODAL, HandlingTargets.TOAST]
- *
- * // Using custom strings
- * targets: ['custom-sidebar', 'my-notification-center']
- *
- * // Mixing both
- * targets: [HandlingTargets.MODAL, 'custom-popup', HandlingTargets.CONSOLE]
- * ```
- *
- * @public
- */
-type HandlingTarget = HandlingTargets | string;
-/**
- * Action to display notifications in specified UI targets.
- * Used to notify applications to handle error messages through the indicated display mechanisms.
- *
- * @example
- * ```typescript
- * {
- *   action: 'notify',
- *   payload: {
- *     targets: [HandlingTargets.TOAST, 'custom-sidebar'],
- *     title: 'Error occurred',
- *     duration: 5000
- *   }
- * }
- * ```
- *
- * @public
- */
-type NotifyAction = {
-    action: 'notify';
-    payload: {
-        targets: HandlingTarget[];
-        [key: string]: any;
-    };
-};
-/**
- * Action to log out the current user when an error occurs.
- * Useful for authentication errors or session expiration.
- *
- * @example
- * ```typescript
- * {
- *   action: 'logout',
- *   payload: {
- *     clearStorage: true,
- *     redirectURL: '/login'
- *   }
- * }
- * ```
- *
- * @public
- */
-type LogoutAction = {
-    action: 'logout';
-    payload?: {
-        [key: string]: any;
-    };
-};
-/**
- * Action to redirect the user to a different URL when an error occurs.
- * Commonly used for navigation after authentication errors or access denied scenarios.
- *
- * @example
- * ```typescript
- * {
- *   action: 'redirect',
- *   payload: {
- *     redirectURL: '/login',
- *     delay: 2000,
- *     replace: true,
- *   }
- * }
- * ```
- *
- * @public
- */
-type RedirectAction = {
-    action: 'redirect';
-    payload: {
-        redirectURL: string;
-        [key: string]: any;
-    };
-};
-/**
- * Custom action type for application-specific actions.
- * This type is essential for proper TypeScript discrimination in the ErrorAction union.
- * Without this, TypeScript cannot properly distinguish between predefined and custom actions.
- *
- * @example
- * ```typescript
- * {
- *   action: 'custom',
- *   payload: {
- *     type: 'analytics',
- *     event: 'error_occurred',
- *     category: 'authentication',
- *     severity: 'high'
- *   }
- * }
- *
- * {
- *   action: 'custom',
- *   payload: {
- *     type: 'show-modal',
- *     modalId: 'error-modal',
- *     title: 'Error',
- *     message: 'Something went wrong'
- *   }
+ *   retryCount: 3,
+ *   // Application-specific behavior can be stored here:
+ *   shouldNotify: true,
+ *   notifyTargets: ['toast', 'banner'],
+ *   redirectTo: '/login'
  * }
  * ```
  *
  * @public
  */
-type CustomAction = {
-    action: 'custom';
-    payload?: Record<string, any>;
-};
-/**
- * Union type of all possible error actions.
- * Includes predefined actions (NotifyAction, LogoutAction, RedirectAction)
- * and CustomAction for application-specific actions.
- *
- * @public
- */
-type ErrorAction = NotifyAction | LogoutAction | RedirectAction | CustomAction;
+type ErrorXMetadata = Record<string, unknown>;
 /**
  * Configuration options for creating an ErrorX instance.
  * All properties are optional with sensible defaults.
@@ -178,6 +33,10 @@ type ErrorAction = NotifyAction | LogoutAction | RedirectAction | CustomAction;
  * // ✅ Works - object literal
  * const opts = { message: 'Error' }
  * new ErrorX(opts)
+ *
+ * // ✅ Works - with type-safe metadata
+ * type MyMeta = { userId: number; action: string };
+ * new ErrorX<MyMeta>({ metadata: { userId: 123, action: 'login' } })
  * ```
  *
  * If ErrorXOptions were a class, you would need to instantiate it:
@@ -192,25 +51,43 @@ type ErrorAction = NotifyAction | LogoutAction | RedirectAction | CustomAction;
  *
  * @public
  */
-type ErrorXOptions = {
+type ErrorXOptions<TMetadata extends ErrorXMetadata = ErrorXMetadata> = {
     /** Technical error message (default: 'An error occurred') */
     message?: string;
     /** Error type/name (default: 'Error') */
     name?: string;
     /** Error identifier code (auto-generated from name if not provided) */
     code?: string | number;
-    /** User-friendly message for UI display (default: undefined) */
+    /** User-friendly message for UI display */
     uiMessage?: string | undefined;
-    /** Original error that caused this error (preserves error chain) */
-    cause?: Error | unknown;
-    /** Additional context and debugging information (default: undefined) */
-    metadata?: ErrorMetadata;
-    /** Actions to perform when this error occurs (default: undefined) */
-    actions?: ErrorAction[];
-    /** HTTP status code (100-599) for HTTP-related errors (default: undefined) */
+    /** 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 */
     httpStatus?: number | undefined;
     /** Error type for categorization */
     type?: string | undefined;
+    /** Source URL related to the error (API endpoint, page URL, resource URL) */
+    sourceUrl?: string | undefined;
+    /** Documentation URL for this specific error */
+    docsUrl?: string | undefined;
+    /** Where the error originated (service name, module, component) */
+    source?: string | undefined;
+};
+/**
+ * Simplified representation of an error cause for serialization.
+ * Used to store error chain information without circular references.
+ *
+ * @public
+ */
+type ErrorXCause = {
+    /** Error message */
+    message: string;
+    /** Error name (optional) */
+    name?: string;
+    /** Stack trace (optional) */
+    stack?: string;
 };
 /**
  * JSON-serializable representation of an ErrorX instance.
@@ -226,21 +103,20 @@ type ErrorXOptions = {
  *   stack: 'Error: Authentication failed.\n    at login (auth.ts:42:15)',
  *   metadata: { userId: 123, loginAttempt: 3 },
  *   timestamp: '2024-01-15T10:30:45.123Z',
- *   actions: [
- *     { action: 'logout', payload: { clearStorage: true } }
- *   ],
  *   cause: {
  *     name: 'NetworkError',
  *     message: 'Request timeout.',
- *     code: 'NETWORK_TIMEOUT',
- *     // ... other error properties
- *   }
+ *     stack: '...'
+ *   },
+ *   sourceUrl: 'https://api.example.com/auth',
+ *   docsUrl: 'https://docs.example.com/errors#auth-failed',
+ *   source: 'auth-service'
  * }
  * ```
  *
  * @public
  */
-type SerializableError = {
+type ErrorXSerialized = {
     /** Error type/name */
     name: string;
     /** Technical error message */
@@ -252,24 +128,58 @@ type SerializableError = {
     /** Stack trace (optional) */
     stack?: string;
     /** Additional context and debugging information */
-    metadata: ErrorMetadata | undefined;
+    metadata: ErrorXMetadata | undefined;
     /** ISO timestamp when error was created */
     timestamp: string;
-    /** Actions to perform when this error occurs */
-    actions?: ErrorAction[];
-    /** Serialized cause error (for error chaining) */
-    cause?: SerializableError;
+    /** Simplified cause error (for error chaining) */
+    cause?: ErrorXCause;
     /** HTTP status code for HTTP-related errors */
     httpStatus?: number;
     /** Error type for categorization */
     type?: string;
+    /** Source URL related to the error */
+    sourceUrl?: string;
+    /** Documentation URL for this error */
+    docsUrl?: string;
+    /** Where the error originated */
+    source?: string;
 };
 
+/**
+ * Configuration interface for ErrorX global settings
+ *
+ * @public
+ */
+interface ErrorXConfig {
+    /** Default source identifier for all errors (e.g., service name, module name) */
+    source?: string;
+    /** Base URL for error documentation */
+    docsBaseURL?: string;
+    /** Mapping of error codes to documentation paths */
+    docsMap?: Record<string, string>;
+    /**
+     * Control stack trace cleaning behavior
+     * - true: Enable automatic stack trace cleaning (default)
+     * - false: Disable stack trace cleaning entirely
+     * - string[]: Custom patterns to match and remove from stack traces
+     */
+    cleanStack?: boolean | string[];
+}
 /**
  * Enhanced Error class with rich metadata, type-safe error handling, and intelligent error conversion.
  *
  * @example
  * ```typescript
+ * // Configure globally (optional)
+ * ErrorX.configure({
+ *   source: 'my-service',
+ *   docsBaseURL: 'https://docs.example.com',
+ *   docsMap: {
+ *     'AUTH_FAILED': 'errors/authentication',
+ *     'DB_ERROR': 'errors/database'
+ *   }
+ * })
+ *
  * // Basic usage
  * const error = new ErrorX({ message: 'Database connection failed' })
  *
@@ -281,68 +191,111 @@ type SerializableError = {
  *   uiMessage: 'Please check your credentials',
  *   metadata: { userId: 123, loginAttempt: 3 }
  * })
+ *
+ * // With type-safe metadata
+ * type MyMetadata = { userId: number; action: string };
+ * const error = new ErrorX<MyMetadata>({
+ *   message: 'Action failed',
+ *   metadata: { userId: 123, action: 'delete' }
+ * })
+ * // error.metadata?.userId is typed as number
  * ```
  *
  * @public
  */
-declare class ErrorX extends Error {
+declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends Error {
+    /** Global configuration for all ErrorX instances */
+    private static _config;
     /** Error identifier code, auto-generated from name if not provided */
-    readonly code: string;
+    code: string;
     /** User-friendly message suitable for display in UI */
-    readonly uiMessage: string | undefined;
+    uiMessage: string | undefined;
     /** Additional context and metadata associated with the error */
-    readonly metadata: ErrorMetadata | undefined;
+    metadata: TMetadata | undefined;
     /** Timestamp when the error was created */
-    readonly timestamp: Date;
-    /** Error actions for UI behavior and handling */
-    readonly actions: ErrorAction[] | undefined;
+    timestamp: Date;
     /** HTTP status code (100-599) for HTTP-related errors */
-    readonly httpStatus: number | undefined;
+    httpStatus: number | undefined;
     /** Error type for categorization */
-    readonly type: string | undefined;
+    type: string | undefined;
+    /** Source URL related to the error (API endpoint, page URL, resource URL) */
+    sourceUrl: string | undefined;
+    /** Documentation URL for this specific error */
+    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.
      *
-     * @param messageOrOptions - Error message string, ErrorXOptions object, or any value to convert to ErrorX
-     * @param additionalOptions - Additional options when first parameter is a string (optional)
+     * @param messageOrOptions - Error message string or ErrorXOptions object (optional)
      *
      * @example
      * ```typescript
+     * // Create with default message
+     * const error1 = new ErrorX()
+     *
      * // Create with string message only
-     * const error1 = new ErrorX('Database query failed')
+     * const error2 = new ErrorX('Database query failed')
      *
-     * // Create with string message and additional options
-     * const error2 = new ErrorX('Database query failed', {
+     * // Create with options object
+     * const error3 = new ErrorX({
+     *   message: 'Database query failed',
      *   name: 'DatabaseError',
      *   code: 'DB_QUERY_FAILED',
      *   uiMessage: 'Unable to load data. Please try again.',
      *   metadata: { query: 'SELECT * FROM users', timeout: 5000 }
      * })
      *
-     * // Create with options object (backward compatible)
-     * const error3 = new ErrorX({
-     *   message: 'Database query failed',
-     *   name: 'DatabaseError',
-     *   code: 'DB_QUERY_FAILED',
-     *   actions: [
-     *     { action: 'notify', payload: { targets: [HandlingTargets.TOAST] } }
-     *   ]
+     * // With type-safe metadata
+     * type MyMeta = { userId: number };
+     * const error4 = new ErrorX<MyMeta>({
+     *   message: 'User action failed',
+     *   metadata: { userId: 123 }
      * })
      *
-     * // Create with unknown input (smart conversion)
+     * // For converting unknown errors, use ErrorX.from()
      * const apiError = { message: 'User not found', code: 404 }
-     * const error4 = new ErrorX(apiError)
-     *
-     * // Create with no options (uses defaults)
-     * const error5 = new ErrorX()
+     * const error5 = ErrorX.from(apiError)
      * ```
      */
-    constructor(messageOrOptions?: string | ErrorXOptions | unknown, additionalOptions?: Partial<ErrorXOptions>);
+    constructor(messageOrOptions?: string | ErrorXOptions<TMetadata>);
     /**
      * Returns the default error name.
      * @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.
+     *
+     * @param config - Configuration object
+     *
+     * @example
+     * ```typescript
+     * ErrorX.configure({
+     *   source: 'my-api-service',
+     *   docsBaseURL: 'https://docs.example.com/errors',
+     *   docsMap: {
+     *     'AUTH_FAILED': 'authentication-errors',
+     *     'DB_ERROR': 'database-errors'
+     *   }
+     * })
+     * ```
+     */
+    static configure(config: ErrorXConfig): void;
+    /**
+     * Get the current global configuration.
+     * Returns null if no configuration has been set.
+     */
+    static getConfig(): ErrorXConfig | null;
     /**
      * Validates HTTP status code to ensure it's within valid range (100-599)
      *
@@ -382,13 +335,13 @@ declare class ErrorX extends Error {
     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.
      * This provides cleaner stack traces that focus on user code.
@@ -412,21 +365,6 @@ declare class ErrorX extends Error {
      * ```
      */
     private static processErrorStack;
-    /**
-     * Formats error messages with proper capitalization and punctuation.
-     * Ensures consistent message formatting across all ErrorX instances.
-     *
-     * @param message - Raw error message to format (optional)
-     * @returns Formatted message with proper capitalization and punctuation
-     *
-     * @example
-     * ```typescript
-     * formatMessage('database connection failed') // 'Database connection failed.'
-     * formatMessage('user not found. please check credentials') // 'User not found. Please check credentials.'
-     * formatMessage() // 'An error occurred'
-     * ```
-     */
-    private static formatMessage;
     /**
      * Creates a new ErrorX instance with additional metadata merged with existing metadata.
      * The original error properties are preserved while extending the metadata.
@@ -448,7 +386,7 @@ declare class ErrorX extends Error {
      * // Result: metadata = { endpoint: '/users', retryCount: 3, userId: 123 }
      * ```
      */
-    withMetadata(additionalMetadata: ErrorMetadata): ErrorX;
+    withMetadata(additionalMetadata: Partial<TMetadata>): ErrorX<TMetadata>;
     /**
      * Type guard that checks if a value is an ErrorX instance.
      *
@@ -467,7 +405,7 @@ declare class ErrorX extends Error {
      * }
      * ```
      */
-    static isErrorX(value: unknown): value is ErrorX;
+    static isErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata>(value: unknown): value is ErrorX<TMetadata>;
     /**
      * Converts unknown input into ErrorXOptions with intelligent property extraction.
      * Handles strings, regular Error objects, API response objects, and unknown values.
@@ -488,10 +426,10 @@ declare class ErrorX extends Error {
      * @example
      * ```typescript
      * // Convert string error
-     * const error1 = ErrorX.toErrorX('Something went wrong')
+     * const error1 = ErrorX.from('Something went wrong')
      *
      * // Convert regular Error
-     * const error2 = ErrorX.toErrorX(new Error('Database failed'))
+     * const error2 = ErrorX.from(new Error('Database failed'))
      *
      * // Convert API response object
      * const apiError = {
@@ -499,26 +437,13 @@ declare class ErrorX extends Error {
      *   code: 'USER_404',
      *   statusText: 'Not Found'
      * }
-     * const error3 = ErrorX.toErrorX(apiError)
+     * const error3 = ErrorX.from(apiError)
      * ```
      */
-    static toErrorX(error: unknown): ErrorX;
-    /**
-     * Public wrapper for processing error stack traces with delimiter.
-     * Delegates to the private processErrorStack method for implementation.
-     *
-     * @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 error = new Error('Something failed')
-     * const cleanStack = ErrorX.processStack(error, 'my-app-entry')
-     * // Returns stack trace starting after the line containing 'my-app-entry'
-     * ```
-     */
-    static processStack(error: Error, delimiter: string): string;
+    static from<TMetadata extends ErrorXMetadata = ErrorXMetadata>(error: ErrorX<TMetadata>): ErrorX<TMetadata>;
+    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.
@@ -533,7 +458,7 @@ declare class ErrorX extends Error {
      * // Returns new ErrorX with stack trace starting after 'database-layer'
      * ```
      */
-    cleanStackTrace(delimiter?: string): ErrorX;
+    cleanStackTrace(delimiter?: string): ErrorX<TMetadata>;
     /**
      * Converts the ErrorX instance to a detailed string representation.
      * Includes error name, message, code, timestamp, metadata, and stack trace.
@@ -572,7 +497,7 @@ declare class ErrorX extends Error {
      * // Can be safely passed to JSON.stringify() or sent over network
      * ```
      */
-    toJSON(): SerializableError;
+    toJSON(): ErrorXSerialized;
     /**
      * Deserializes a JSON object back into an ErrorX instance.
      * Recursively reconstructs the error chain and restores all properties.
@@ -595,441 +520,429 @@ declare class ErrorX extends Error {
      * // Fully restored ErrorX instance with all properties
      * ```
      */
-    static fromJSON(serialized: SerializableError): ErrorX;
-    /**
-     * HTTP error presets for common HTTP status codes.
-     *
-     * ## Features
-     * - **Pre-configured error templates** for common HTTP status codes (400-511)
-     * - **Type-safe** with TypeScript support
-     * - **Fully customizable** via destructuring and override pattern
-     * - **User-friendly messages** included for all presets
-     * - **Categorized by type** - all HTTP presets include `type: 'http'`
-     *
-     * ## Usage Patterns
-     *
-     * ### 1. Direct Usage
-     * Use a preset as-is without any modifications:
-     * ```typescript
-     * throw new ErrorX(ErrorX.HTTP.NOT_FOUND)
-     * // Result: 404 error with default message and UI message
-     * ```
-     *
-     * ### 2. Override Specific Fields
-     * Customize the error while keeping other preset values:
-     * ```typescript
-     * throw new ErrorX({
-     *   ...ErrorX.HTTP.NOT_FOUND,
-     *   message: 'User not found',
-     *   metadata: { userId: 123 }
-     * })
-     * // Result: 404 error with custom message but keeps httpStatus, code, name, uiMessage, type
-     * ```
-     *
-     * ### 3. Add Metadata and Actions
-     * Enhance presets with additional context and behaviors:
-     * ```typescript
-     * throw new ErrorX({
-     *   ...ErrorX.HTTP.UNAUTHORIZED,
-     *   metadata: { attemptedAction: 'viewProfile', userId: 456 },
-     *   actions: [
-     *     { action: 'logout', payload: { clearStorage: true } },
-     *     { action: 'redirect', payload: { redirectURL: '/login' } }
-     *   ]
-     * })
-     * ```
-     *
-     * ### 4. Add Error Cause
-     * Chain errors by adding a cause:
-     * ```typescript
-     * try {
-     *   // some operation
-     * } catch (originalError) {
-     *   throw new ErrorX({
-     *     ...ErrorX.HTTP.INTERNAL_SERVER_ERROR,
-     *     cause: originalError,
-     *     metadata: { operation: 'database-query' }
-     *   })
-     * }
-     * ```
-     *
-     * ## Common HTTP Presets
-     *
-     * ### 4xx Client Errors
-     * - `BAD_REQUEST` (400) - Invalid request data
-     * - `UNAUTHORIZED` (401) - Authentication required
-     * - `FORBIDDEN` (403) - Insufficient permissions
-     * - `NOT_FOUND` (404) - Resource not found
-     * - `METHOD_NOT_ALLOWED` (405) - HTTP method not allowed
-     * - `CONFLICT` (409) - Resource conflict
-     * - `UNPROCESSABLE_ENTITY` (422) - Validation failed
-     * - `TOO_MANY_REQUESTS` (429) - Rate limit exceeded
-     *
-     * ### 5xx Server Errors
-     * - `INTERNAL_SERVER_ERROR` (500) - Unexpected server error
-     * - `NOT_IMPLEMENTED` (501) - Feature not implemented
-     * - `BAD_GATEWAY` (502) - Upstream server error
-     * - `SERVICE_UNAVAILABLE` (503) - Service temporarily down
-     * - `GATEWAY_TIMEOUT` (504) - Upstream timeout
-     *
-     * @example
-     * ```typescript
-     * // API endpoint example
-     * app.get('/users/:id', async (req, res) => {
-     *   const user = await db.users.findById(req.params.id)
-     *
-     *   if (!user) {
-     *     throw new ErrorX({
-     *       ...ErrorX.HTTP.NOT_FOUND,
-     *       message: 'User not found',
-     *       metadata: { userId: req.params.id }
-     *     })
-     *   }
-     *
-     *   res.json(user)
-     * })
-     *
-     * // Authentication middleware example
-     * const requireAuth = (req, res, next) => {
-     *   if (!req.user) {
-     *     throw new ErrorX({
-     *       ...ErrorX.HTTP.UNAUTHORIZED,
-     *       actions: [
-     *         { action: 'redirect', payload: { redirectURL: '/login' } }
-     *       ]
-     *     })
-     *   }
-     *   next()
-     * }
-     *
-     * // Rate limiting example
-     * if (isRateLimited(req.ip)) {
-     *   throw new ErrorX({
-     *     ...ErrorX.HTTP.TOO_MANY_REQUESTS,
-     *     metadata: {
-     *       ip: req.ip,
-     *       retryAfter: 60
-     *     }
-     *   })
-     * }
-     * ```
-     *
-     * @public
-     */
-    static readonly HTTP: {
-        readonly BAD_REQUEST: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly UNAUTHORIZED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly PAYMENT_REQUIRED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly FORBIDDEN: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly NOT_FOUND: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly METHOD_NOT_ALLOWED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly NOT_ACCEPTABLE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly PROXY_AUTHENTICATION_REQUIRED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly REQUEST_TIMEOUT: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly CONFLICT: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly GONE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly LENGTH_REQUIRED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly PRECONDITION_FAILED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly PAYLOAD_TOO_LARGE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly URI_TOO_LONG: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly UNSUPPORTED_MEDIA_TYPE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly RANGE_NOT_SATISFIABLE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly EXPECTATION_FAILED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly IM_A_TEAPOT: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly UNPROCESSABLE_ENTITY: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly LOCKED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly FAILED_DEPENDENCY: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly TOO_EARLY: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly UPGRADE_REQUIRED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly PRECONDITION_REQUIRED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly TOO_MANY_REQUESTS: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly REQUEST_HEADER_FIELDS_TOO_LARGE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly UNAVAILABLE_FOR_LEGAL_REASONS: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly INTERNAL_SERVER_ERROR: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly NOT_IMPLEMENTED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly BAD_GATEWAY: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly SERVICE_UNAVAILABLE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly GATEWAY_TIMEOUT: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly HTTP_VERSION_NOT_SUPPORTED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly VARIANT_ALSO_NEGOTIATES: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly INSUFFICIENT_STORAGE: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly LOOP_DETECTED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly NOT_EXTENDED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-        readonly NETWORK_AUTHENTICATION_REQUIRED: {
-            httpStatus: number;
-            code: string;
-            name: string;
-            message: string;
-            uiMessage: string;
-            type: string;
-        };
-    };
+    static fromJSON<TMetadata extends ErrorXMetadata = ErrorXMetadata>(serialized: ErrorXSerialized): ErrorX<TMetadata>;
 }
 
-export { type CustomAction, type ErrorAction, type ErrorMetadata, ErrorX, type ErrorXOptions, type HandlingTarget, HandlingTargets, type LogoutAction, type NotifyAction, type RedirectAction, type SerializableError };
+/**
+ * HTTP error presets for common HTTP status codes.
+ *
+ * These presets provide pre-configured error options for standard HTTP error responses,
+ * including appropriate status codes, error codes, names, messages (sentence case), and user-friendly UI messages.
+ *
+ * ## Usage Patterns
+ *
+ * ### 1. Use Preset Directly
+ * Create an error with all preset values:
+ * ```typescript
+ * throw new ErrorX(http.notFound)
+ * // Result: 404 error with message "Not found.", code, name, uiMessage, and type
+ * ```
+ *
+ * ### 2. Override Specific Fields
+ * Customize the error while keeping other preset values:
+ * ```typescript
+ * throw new ErrorX({
+ *   ...http.notFound,
+ *   message: 'User not found',
+ *   metadata: { userId: 123 }
+ * })
+ * // Result: 404 error with custom message but keeps httpStatus, code, name, uiMessage, type
+ * ```
+ *
+ * ### 3. Add Metadata
+ * Enhance presets with additional context:
+ * ```typescript
+ * throw new ErrorX({
+ *   ...http.unauthorized,
+ *   metadata: { attemptedAction: 'viewProfile', userId: 456 }
+ * })
+ * ```
+ *
+ * ### 4. Add Error Cause
+ * Chain errors by adding a cause:
+ * ```typescript
+ * try {
+ *   // some operation
+ * } catch (originalError) {
+ *   throw new ErrorX({
+ *     ...http.internalServerError,
+ *     cause: originalError,
+ *     metadata: { operation: 'database-query' }
+ *   })
+ * }
+ * ```
+ *
+ * ## Common HTTP Presets
+ *
+ * ### 4xx Client Errors
+ * - `badRequest` (400) - Invalid request data
+ * - `unauthorized` (401) - Authentication required
+ * - `forbidden` (403) - Insufficient permissions
+ * - `notFound` (404) - Resource not found
+ * - `methodNotAllowed` (405) - HTTP method not allowed
+ * - `conflict` (409) - Resource conflict
+ * - `unprocessableEntity` (422) - Validation failed
+ * - `tooManyRequests` (429) - Rate limit exceeded
+ *
+ * ### 5xx Server Errors
+ * - `internalServerError` (500) - Unexpected server error
+ * - `notImplemented` (501) - Feature not implemented
+ * - `badGateway` (502) - Upstream server error
+ * - `serviceUnavailable` (503) - Service temporarily down
+ * - `gatewayTimeout` (504) - Upstream timeout
+ *
+ * @example
+ * ```typescript
+ * // API endpoint example
+ * app.get('/users/:id', async (req, res) => {
+ *   const user = await db.users.findById(req.params.id)
+ *
+ *   if (!user) {
+ *     throw new ErrorX({
+ *       ...http.notFound,
+ *       message: 'User not found',
+ *       metadata: { userId: req.params.id }
+ *     })
+ *   }
+ *
+ *   res.json(user)
+ * })
+ *
+ * // Authentication middleware example
+ * const requireAuth = (req, res, next) => {
+ *   if (!req.user) {
+ *     throw new ErrorX(http.unauthorized)
+ *   }
+ *   next()
+ * }
+ *
+ * // Rate limiting example
+ * if (isRateLimited(req.ip)) {
+ *   throw new ErrorX({
+ *     ...http.tooManyRequests,
+ *     metadata: {
+ *       ip: req.ip,
+ *       retryAfter: 60
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * @public
+ */
+declare const http: {
+    readonly badRequest: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly unauthorized: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly paymentRequired: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly forbidden: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly notFound: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly methodNotAllowed: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly notAcceptable: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly proxyAuthenticationRequired: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly requestTimeout: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly conflict: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly gone: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly lengthRequired: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly preconditionFailed: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly payloadTooLarge: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly uriTooLong: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly unsupportedMediaType: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly rangeNotSatisfiable: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly expectationFailed: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly imATeapot: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly unprocessableEntity: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly locked: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly failedDependency: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly tooEarly: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly upgradeRequired: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly preconditionRequired: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly tooManyRequests: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly requestHeaderFieldsTooLarge: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly unavailableForLegalReasons: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly internalServerError: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly notImplemented: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly badGateway: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly serviceUnavailable: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly gatewayTimeout: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly httpVersionNotSupported: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly variantAlsoNegotiates: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly insufficientStorage: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly loopDetected: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly notExtended: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+    readonly networkAuthenticationRequired: {
+        httpStatus: number;
+        code: string;
+        name: string;
+        message: string;
+        uiMessage: string;
+        type: string;
+    };
+};
+
+export { ErrorX, type ErrorXCause, type ErrorXConfig, type ErrorXMetadata, type ErrorXOptions, type ErrorXSerialized, http };