@bombillazo/error-x 0.4.6 → 0.5.0

package/dist/index.d.cts

@@ -64,12 +64,8 @@ type ErrorXOptions<TMetadata extends ErrorXMetadata = ErrorXMetadata> = {
     cause?: ErrorXCause | Error | unknown;
     /** Additional context and debugging information */
     metadata?: TMetadata | undefined;
-    /** Error type for categorization */
-    type?: string | undefined;
-    /** Documentation URL for this specific error */
-    docsUrl?: string | undefined;
-    /** Where the error originated (service name, module, component) */
-    source?: string | undefined;
+    /** HTTP status code associated with this error */
+    httpStatus?: number | undefined;
 };
 /**
  * Simplified representation of an error cause for serialization.
@@ -85,13 +81,30 @@ type ErrorXCause = {
     /** Stack trace (optional) */
     stack?: string;
 };
+/**
+ * Context passed to the transform function when creating errors via `.create()`.
+ * Contains information about the preset being used.
+ *
+ * @public
+ */
+type ErrorXTransformContext = {
+    /** The preset key used (if any) */
+    presetKey: string | number | undefined;
+};
+/**
+ * Transform function signature for custom error classes.
+ * Transforms options after merge but before instantiation.
+ *
+ * @public
+ */
+type ErrorXTransform<TMetadata extends ErrorXMetadata = ErrorXMetadata> = (opts: ErrorXOptions<ErrorXMetadata>, ctx: ErrorXTransformContext) => ErrorXOptions<TMetadata>;
 /**
  * JSON-serializable representation of an ErrorX instance.
  * Used for transmitting errors over network or storing in databases.
  *
  * @example
  * ```typescript
- * const serialized: SerializableError = {
+ * const serialized: ErrorXSerialized = {
  *   name: 'AuthError',
  *   message: 'Authentication failed.',
  *   code: 'AUTH_FAILED',
@@ -99,13 +112,16 @@ type ErrorXCause = {
  *   stack: 'Error: Authentication failed.\n    at login (auth.ts:42:15)',
  *   metadata: { userId: 123, loginAttempt: 3 },
  *   timestamp: 1705315845123,
- *   cause: {
+ *   httpStatus: 401,
+ *   original: {
  *     name: 'NetworkError',
  *     message: 'Request timeout.',
  *     stack: '...'
  *   },
- *   docsUrl: 'https://docs.example.com/errors#auth-failed',
- *   source: 'auth-service'
+ *   chain: [
+ *     { name: 'AuthError', message: 'Authentication failed.' },
+ *     { name: 'NetworkError', message: 'Request timeout.' }
+ *   ]
  * }
  * ```
  *
@@ -126,15 +142,20 @@ type ErrorXSerialized = {
     metadata: ErrorXMetadata | undefined;
     /** Unix epoch timestamp (milliseconds) when error was created */
     timestamp: number;
-    /** Simplified cause error (for error chaining) */
-    cause?: ErrorXCause;
-    /** Error type for categorization */
-    type?: string;
-    /** Documentation URL for this error */
-    docsUrl?: string;
-    /** Where the error originated */
-    source?: string;
+    /** HTTP status code associated with this error */
+    httpStatus?: number;
+    /** Serialized non-ErrorX entity this was wrapped from (if created via ErrorX.from()) */
+    original?: ErrorXCause;
+    /** Serialized error chain timeline (this error and all ancestors) */
+    chain?: ErrorXCause[];
 };
+/**
+ * Type representing valid preset keys for error creation.
+ * Allows both string and number keys while preventing accidental misuse.
+ *
+ * @public
+ */
+type ErrorXBasePresetKey = (number & {}) | (string & {});
 
 /**
  * Configuration interface for ErrorX global settings
@@ -142,12 +163,6 @@ type ErrorXSerialized = {
  * @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)
@@ -168,12 +183,6 @@ interface ErrorXConfig {
  * ```typescript
  * // Configure globally (optional)
  * ErrorX.configure({
- *   source: 'my-service',
- *   docsBaseURL: 'https://docs.example.com',
- *   docsMap: {
- *     'AUTH_FAILED': 'errors/authentication',
- *     'DB_ERROR': 'errors/database'
- *   },
  *   cleanStackDelimiter: 'my-app-entry' // Clean stack traces after this line
  * })
  *
@@ -211,14 +220,27 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
     metadata: TMetadata | undefined;
     /** Unix epoch timestamp (milliseconds) when the error was created */
     timestamp: number;
-    /** Error type for categorization */
-    type: 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;
+    /** HTTP status code associated with this error */
+    httpStatus: number | undefined;
+    /** Serialized non-ErrorX entity this was wrapped from (if created via ErrorX.from()) */
+    original: ErrorXCause | undefined;
+    /** Error chain timeline: [this, parent, grandparent, ...] - single source of truth */
+    private _chain;
+    /**
+     * Gets the immediate parent ErrorX in the chain (if any).
+     * @returns The ErrorX that caused this error, or undefined if this is the root
+     */
+    get parent(): ErrorX | undefined;
+    /**
+     * Gets the deepest ErrorX in the chain (the original root cause).
+     * @returns The root cause ErrorX, or undefined if chain has only this error
+     */
+    get root(): ErrorX | undefined;
+    /**
+     * Gets the full error chain timeline.
+     * @returns Array of ErrorX instances: [this, parent, grandparent, ...]
+     */
+    get chain(): readonly ErrorX[];
     /**
      * Creates a new ErrorX instance with enhanced error handling capabilities.
      *
@@ -274,12 +296,7 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      * @example
      * ```typescript
      * ErrorX.configure({
-     *   source: 'my-api-service',
-     *   docsBaseURL: 'https://docs.example.com/errors',
-     *   docsMap: {
-     *     'AUTH_FAILED': 'authentication-errors',
-     *     'DB_ERROR': 'database-errors'
-     *   },
+     *   cleanStack: true, // Enable stack trace cleaning
      *   cleanStackDelimiter: 'app-entry-point' // Trim stack traces after this line
      * })
      * ```
@@ -301,13 +318,6 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      * ```
      */
     static resetConfig(): void;
-    /**
-     * Validates and normalizes the type field
-     *
-     * @param type - Type value to validate
-     * @returns Validated type string or undefined if invalid/empty
-     */
-    private static validateType;
     /**
      * Validates if an object is a valid ErrorXOptions object.
      * Checks that the object only contains accepted ErrorXOptions fields.
@@ -331,15 +341,6 @@ 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 from ErrorXCause.
-     *
-     * @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 preserveOriginalStackFromCause;
     /**
      * 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.
@@ -416,8 +417,12 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      * Handles strings, regular Error objects, API response objects, and unknown values.
      * Extracts metadata directly from objects if present.
      *
-     * @param error - Value to convert to ErrorX
-     * @returns ErrorX instance with extracted properties
+     * This is a "wrapping" operation - the resulting ErrorX represents the same error
+     * in ErrorX form. The original source is stored in the `original` property.
+     *
+     * @param payload - Value to convert to ErrorX
+     * @param overrides - Optional overrides to deep-merge with extracted properties
+     * @returns ErrorX instance with extracted properties and `original` set
      *
      * @example
      * ```typescript
@@ -435,12 +440,19 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      * }
      * const error3 = ErrorX.from(apiError)
      * // error3.metadata = { userId: 123, endpoint: '/api/users' }
+     * // error3.original = { message: 'User not found', name: undefined, stack: undefined }
+     *
+     * // With overrides
+     * const error4 = ErrorX.from(new Error('Connection failed'), {
+     *   httpStatus: 500,
+     *   metadata: { context: 'db-layer' }
+     * })
      * ```
      */
-    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;
+    static from<TMetadata extends ErrorXMetadata = ErrorXMetadata>(error: ErrorX<TMetadata>, overrides?: Partial<ErrorXOptions<TMetadata>>): ErrorX<TMetadata>;
+    static from<TMetadata extends ErrorXMetadata = ErrorXMetadata>(payload: Error, overrides?: Partial<ErrorXOptions<TMetadata>>): ErrorX<TMetadata>;
+    static from<TMetadata extends ErrorXMetadata = ErrorXMetadata>(payload: string, overrides?: Partial<ErrorXOptions<TMetadata>>): ErrorX<TMetadata>;
+    static from<TMetadata extends ErrorXMetadata = ErrorXMetadata>(payload: unknown, overrides?: Partial<ErrorXOptions<TMetadata>>): ErrorX<TMetadata>;
     /**
      * Converts the ErrorX instance to a detailed string representation.
      * Includes error name, message, code, timestamp, metadata, and stack trace.
@@ -503,467 +515,1093 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      * ```
      */
     static fromJSON<TMetadata extends ErrorXMetadata = ErrorXMetadata>(serialized: ErrorXSerialized): ErrorX<TMetadata>;
+    /**
+     * Creates a new instance of this error class using optional presets and overrides.
+     * This is a factory method that supports preset-based error creation with
+     * full TypeScript autocomplete for preset keys.
+     *
+     * Define static properties on your subclass to customize behavior:
+     * - `presets`: Record of preset configurations keyed by identifier
+     * - `defaultPreset`: Key of preset to use as fallback
+     * - `defaults`: Default values for all errors of this class
+     * - `transform`: Function to transform options before instantiation
+     *
+     * Supported call signatures:
+     * - `create()` - uses defaultPreset
+     * - `create(presetKey)` - uses specified preset
+     * - `create(presetKey, overrides)` - preset with overrides
+     * - `create(overrides)` - just overrides, uses defaultPreset
+     *
+     * @param presetKeyOrOverrides - Preset key (string/number) or overrides object
+     * @param overrides - Optional overrides when first arg is preset key
+     * @returns New instance of this error class
+     *
+     * @example
+     * ```typescript
+     * class DBError extends ErrorX<{ query?: string }> {
+     *   static presets = {
+     *     9333: { message: 'Connection timeout', code: 'TIMEOUT' },
+     *     CONN_REFUSED: { message: 'Connection refused', code: 'CONN_REFUSED' },
+     *     GENERIC: { message: 'A database error occurred', code: 'ERROR' },
+     *   }
+     *   static defaultPreset = 'GENERIC'
+     *   static defaults = { httpStatus: 500 }
+     *   static transform = (opts, ctx) => ({
+     *     ...opts,
+     *     code: `DB_${opts.code}`,
+     *   })
+     * }
+     *
+     * DBError.create()                           // uses defaultPreset
+     * DBError.create(9333)                       // uses preset 9333
+     * DBError.create('CONN_REFUSED')             // uses preset CONN_REFUSED
+     * DBError.create(9333, { message: 'Custom' }) // preset + overrides
+     * DBError.create({ message: 'Custom' })      // just overrides
+     * ```
+     */
+    static create<T extends ErrorXMetadata = ErrorXMetadata>(this: new (options?: ErrorXOptions<T>) => ErrorX<T>, presetKeyOrOverrides?: string | number | Partial<ErrorXOptions<ErrorXMetadata>>, overrides?: Partial<ErrorXOptions<ErrorXMetadata>>): ErrorX<T>;
 }
 
 /**
- * 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.
+ * Database error presets for common scenarios.
+ * Defined outside the class to enable type inference for preset keys.
+ */
+declare const dbPresets: {
+    readonly CONNECTION_FAILED: {
+        readonly code: "CONNECTION_FAILED";
+        readonly name: "DBConnectionError";
+        readonly message: "Failed to connect to database.";
+        readonly uiMessage: "Unable to connect to the database. Please try again later.";
+    };
+    readonly CONNECTION_TIMEOUT: {
+        readonly code: "CONNECTION_TIMEOUT";
+        readonly name: "DBConnectionTimeoutError";
+        readonly message: "Database connection timed out.";
+        readonly uiMessage: "The database connection timed out. Please try again.";
+    };
+    readonly CONNECTION_REFUSED: {
+        readonly code: "CONNECTION_REFUSED";
+        readonly name: "DBConnectionRefusedError";
+        readonly message: "Database connection refused.";
+        readonly uiMessage: "Unable to connect to the database. Please try again later.";
+    };
+    readonly CONNECTION_LOST: {
+        readonly code: "CONNECTION_LOST";
+        readonly name: "DBConnectionLostError";
+        readonly message: "Database connection lost.";
+        readonly uiMessage: "The database connection was lost. Please try again.";
+    };
+    readonly QUERY_FAILED: {
+        readonly code: "QUERY_FAILED";
+        readonly name: "DBQueryError";
+        readonly message: "Database query failed.";
+        readonly uiMessage: "The database operation failed. Please try again.";
+    };
+    readonly QUERY_TIMEOUT: {
+        readonly code: "QUERY_TIMEOUT";
+        readonly name: "DBQueryTimeoutError";
+        readonly message: "Database query timed out.";
+        readonly uiMessage: "The database operation took too long. Please try again.";
+    };
+    readonly SYNTAX_ERROR: {
+        readonly code: "SYNTAX_ERROR";
+        readonly name: "DBSyntaxError";
+        readonly message: "Invalid query syntax.";
+        readonly uiMessage: "An internal error occurred. Please contact support.";
+    };
+    readonly UNIQUE_VIOLATION: {
+        readonly code: "UNIQUE_VIOLATION";
+        readonly name: "DBUniqueViolationError";
+        readonly message: "Unique constraint violation.";
+        readonly uiMessage: "This record already exists.";
+        readonly httpStatus: 409;
+    };
+    readonly FOREIGN_KEY_VIOLATION: {
+        readonly code: "FOREIGN_KEY_VIOLATION";
+        readonly name: "DBForeignKeyError";
+        readonly message: "Foreign key constraint violation.";
+        readonly uiMessage: "This operation references a record that does not exist.";
+        readonly httpStatus: 400;
+    };
+    readonly NOT_NULL_VIOLATION: {
+        readonly code: "NOT_NULL_VIOLATION";
+        readonly name: "DBNotNullError";
+        readonly message: "Not null constraint violation.";
+        readonly uiMessage: "A required field is missing.";
+        readonly httpStatus: 400;
+    };
+    readonly CHECK_VIOLATION: {
+        readonly code: "CHECK_VIOLATION";
+        readonly name: "DBCheckViolationError";
+        readonly message: "Check constraint violation.";
+        readonly uiMessage: "The provided data is invalid.";
+        readonly httpStatus: 400;
+    };
+    readonly TRANSACTION_FAILED: {
+        readonly code: "TRANSACTION_FAILED";
+        readonly name: "DBTransactionError";
+        readonly message: "Database transaction failed.";
+        readonly uiMessage: "The operation failed. Please try again.";
+    };
+    readonly DEADLOCK: {
+        readonly code: "DEADLOCK";
+        readonly name: "DBDeadlockError";
+        readonly message: "Database deadlock detected.";
+        readonly uiMessage: "The operation encountered a conflict. Please try again.";
+        readonly httpStatus: 409;
+    };
+    readonly NOT_FOUND: {
+        readonly code: "NOT_FOUND";
+        readonly name: "DBNotFoundError";
+        readonly message: "Record not found.";
+        readonly uiMessage: "The requested record was not found.";
+        readonly httpStatus: 404;
+    };
+    readonly UNKNOWN: {
+        readonly code: "UNKNOWN";
+        readonly name: "DBErrorX";
+        readonly message: "An unknown database error occurred.";
+        readonly uiMessage: "A database error occurred. Please try again later.";
+    };
+};
+/**
+ * Valid preset keys for DBErrorX.create()
+ * Derived from the presets object. Provides autocomplete for known presets
+ * while allowing any string for flexibility.
+ */
+type DBErrorXPresetKey = keyof typeof dbPresets | ErrorXBasePresetKey;
+/**
+ * Metadata type for database errors.
+ * Provides context about the database operation that failed.
  *
- * ## Usage Patterns
+ * @public
+ */
+type DBErrorXMetadata = {
+    /** The SQL query or operation that failed */
+    query?: string;
+    /** The table involved in the operation */
+    table?: string;
+    /** The database name */
+    database?: string;
+    /** The operation type (SELECT, INSERT, UPDATE, DELETE, etc.) */
+    operation?: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'TRANSACTION' | 'CONNECTION' | string;
+    /** The column involved (for constraint errors) */
+    column?: string;
+    /** The constraint name (for constraint violations) */
+    constraint?: string;
+    /** Duration of the operation in milliseconds */
+    duration?: number;
+};
+/**
+ * Database Error class with presets for common database error scenarios.
  *
- * ### 1. Use Preset Directly
- * Create an error with all preset values:
- * ```typescript
- * throw new ErrorX(http[404])
- * // Result: 404 error with message "Not found.", code, name, uiMessage, and type
- * ```
+ * Provides a type-safe way to create database errors with:
+ * - Common error presets (connection, query, timeout, constraints)
+ * - Automatic code prefixing with `DB_`
+ * - Full `instanceof` support
+ * - Typed metadata for database context
  *
- * ### 2. Override Specific Fields
- * Customize the error while keeping other preset values:
+ * @example
  * ```typescript
- * throw new ErrorX({
- *   ...http[404],
- *   message: 'User not found',
- *   metadata: { userId: 123 }
- * })
- * // Result: 404 error with custom message but keeps httpStatus, code, name, uiMessage, type
- * ```
+ * // Basic usage with preset
+ * throw DBErrorX.create('CONNECTION_FAILED')
+ * throw DBErrorX.create('QUERY_FAILED')
+ * throw DBErrorX.create('TIMEOUT')
  *
- * ### 3. Add Metadata
- * Enhance presets with additional context:
- * ```typescript
- * throw new ErrorX({
- *   ...http[401],
- *   metadata: { attemptedAction: 'viewProfile', userId: 456 }
+ * // With metadata
+ * throw DBErrorX.create('QUERY_FAILED', {
+ *   message: 'Failed to fetch user',
+ *   metadata: {
+ *     query: 'SELECT * FROM users WHERE id = ?',
+ *     table: 'users',
+ *     operation: 'SELECT'
+ *   }
  * })
- * ```
  *
- * ### 4. Add Error Cause
- * Chain errors by adding a cause:
- * ```typescript
+ * // With error chaining
  * try {
- *   // some operation
- * } catch (originalError) {
- *   throw new ErrorX({
- *     ...http[500],
- *     cause: originalError,
- *     metadata: { operation: 'database-query' }
- *   })
+ *   await db.query(sql)
+ * } catch (err) {
+ *   throw DBErrorX.create('QUERY_FAILED', { cause: err })
  * }
- * ```
- *
- * ## Common HTTP Presets
- *
- * ### 4xx Client Errors
- * - `400` - Bad Request - Invalid request data
- * - `401` - Unauthorized - Authentication required
- * - `403` - Forbidden - Insufficient permissions
- * - `404` - Not Found - Resource not found
- * - `405` - Method Not Allowed - HTTP method not allowed
- * - `409` - Conflict - Resource conflict
- * - `422` - Unprocessable Entity - Validation failed
- * - `429` - Too Many Requests - Rate limit exceeded
- *
- * ### 5xx Server Errors
- * - `500` - Internal Server Error - Unexpected server error
- * - `501` - Not Implemented - Feature not implemented
- * - `502` - Bad Gateway - Upstream server error
- * - `503` - Service Unavailable - Service temporarily down
- * - `504` - Gateway Timeout - 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[404],
- *       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[401])
- *   }
- *   next()
- * }
+ * // Just overrides (uses default UNKNOWN)
+ * throw DBErrorX.create({ message: 'Database error' })
  *
- * // Rate limiting example
- * if (isRateLimited(req.ip)) {
- *   throw new ErrorX({
- *     ...http[429],
- *     metadata: {
- *       ip: req.ip,
- *       retryAfter: 60
- *     }
- *   })
+ * // instanceof checks
+ * if (error instanceof DBErrorX) {
+ *   console.log(error.metadata?.table)
  * }
  * ```
  *
  * @public
  */
-declare const http: {
-    readonly 400: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
+declare class DBErrorX extends ErrorX<DBErrorXMetadata> {
+    /**
+     * Database error presets for common scenarios.
+     */
+    static presets: {
+        readonly CONNECTION_FAILED: {
+            readonly code: "CONNECTION_FAILED";
+            readonly name: "DBConnectionError";
+            readonly message: "Failed to connect to database.";
+            readonly uiMessage: "Unable to connect to the database. Please try again later.";
+        };
+        readonly CONNECTION_TIMEOUT: {
+            readonly code: "CONNECTION_TIMEOUT";
+            readonly name: "DBConnectionTimeoutError";
+            readonly message: "Database connection timed out.";
+            readonly uiMessage: "The database connection timed out. Please try again.";
+        };
+        readonly CONNECTION_REFUSED: {
+            readonly code: "CONNECTION_REFUSED";
+            readonly name: "DBConnectionRefusedError";
+            readonly message: "Database connection refused.";
+            readonly uiMessage: "Unable to connect to the database. Please try again later.";
+        };
+        readonly CONNECTION_LOST: {
+            readonly code: "CONNECTION_LOST";
+            readonly name: "DBConnectionLostError";
+            readonly message: "Database connection lost.";
+            readonly uiMessage: "The database connection was lost. Please try again.";
+        };
+        readonly QUERY_FAILED: {
+            readonly code: "QUERY_FAILED";
+            readonly name: "DBQueryError";
+            readonly message: "Database query failed.";
+            readonly uiMessage: "The database operation failed. Please try again.";
+        };
+        readonly QUERY_TIMEOUT: {
+            readonly code: "QUERY_TIMEOUT";
+            readonly name: "DBQueryTimeoutError";
+            readonly message: "Database query timed out.";
+            readonly uiMessage: "The database operation took too long. Please try again.";
         };
+        readonly SYNTAX_ERROR: {
+            readonly code: "SYNTAX_ERROR";
+            readonly name: "DBSyntaxError";
+            readonly message: "Invalid query syntax.";
+            readonly uiMessage: "An internal error occurred. Please contact support.";
+        };
+        readonly UNIQUE_VIOLATION: {
+            readonly code: "UNIQUE_VIOLATION";
+            readonly name: "DBUniqueViolationError";
+            readonly message: "Unique constraint violation.";
+            readonly uiMessage: "This record already exists.";
+            readonly httpStatus: 409;
+        };
+        readonly FOREIGN_KEY_VIOLATION: {
+            readonly code: "FOREIGN_KEY_VIOLATION";
+            readonly name: "DBForeignKeyError";
+            readonly message: "Foreign key constraint violation.";
+            readonly uiMessage: "This operation references a record that does not exist.";
+            readonly httpStatus: 400;
+        };
+        readonly NOT_NULL_VIOLATION: {
+            readonly code: "NOT_NULL_VIOLATION";
+            readonly name: "DBNotNullError";
+            readonly message: "Not null constraint violation.";
+            readonly uiMessage: "A required field is missing.";
+            readonly httpStatus: 400;
+        };
+        readonly CHECK_VIOLATION: {
+            readonly code: "CHECK_VIOLATION";
+            readonly name: "DBCheckViolationError";
+            readonly message: "Check constraint violation.";
+            readonly uiMessage: "The provided data is invalid.";
+            readonly httpStatus: 400;
+        };
+        readonly TRANSACTION_FAILED: {
+            readonly code: "TRANSACTION_FAILED";
+            readonly name: "DBTransactionError";
+            readonly message: "Database transaction failed.";
+            readonly uiMessage: "The operation failed. Please try again.";
+        };
+        readonly DEADLOCK: {
+            readonly code: "DEADLOCK";
+            readonly name: "DBDeadlockError";
+            readonly message: "Database deadlock detected.";
+            readonly uiMessage: "The operation encountered a conflict. Please try again.";
+            readonly httpStatus: 409;
+        };
+        readonly NOT_FOUND: {
+            readonly code: "NOT_FOUND";
+            readonly name: "DBNotFoundError";
+            readonly message: "Record not found.";
+            readonly uiMessage: "The requested record was not found.";
+            readonly httpStatus: 404;
+        };
+        readonly UNKNOWN: {
+            readonly code: "UNKNOWN";
+            readonly name: "DBErrorX";
+            readonly message: "An unknown database error occurred.";
+            readonly uiMessage: "A database error occurred. Please try again later.";
+        };
+    };
+    /** Default to UNKNOWN when no preset specified */
+    static defaultPreset: string;
+    /** Default httpStatus for database errors (500 = server error) */
+    static defaults: {
+        httpStatus: number;
+    };
+    /**
+     * Transform that prefixes all codes with `DB_`.
+     */
+    static transform: ErrorXTransform<DBErrorXMetadata>;
+    /**
+     * Creates a DBErrorX from a preset key.
+     *
+     * @param presetKey - Preset key (provides autocomplete for known presets)
+     * @param overrides - Optional overrides for the preset values
+     * @returns DBErrorX instance
+     */
+    static create(presetKey?: DBErrorXPresetKey, overrides?: Partial<ErrorXOptions<DBErrorXMetadata>>): DBErrorX;
+    static create(overrides?: Partial<ErrorXOptions<DBErrorXMetadata>>): DBErrorX;
+}
+
+/**
+ * HTTP status code presets for all standard codes.
+ * Defined outside the class to enable type inference for preset keys.
+ */
+declare const httpPresets: {
+    readonly 400: {
+        readonly code: "BAD_REQUEST";
+        readonly name: "BadRequestError";
+        readonly message: "Bad request.";
+        readonly uiMessage: "The request could not be processed. Please check your input and try again.";
     };
     readonly 401: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "UNAUTHORIZED";
+        readonly name: "UnauthorizedError";
+        readonly message: "Unauthorized.";
+        readonly uiMessage: "Authentication required. Please log in to continue.";
     };
     readonly 402: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "PAYMENT_REQUIRED";
+        readonly name: "PaymentRequiredError";
+        readonly message: "Payment required.";
+        readonly uiMessage: "Payment is required to access this resource.";
     };
     readonly 403: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "FORBIDDEN";
+        readonly name: "ForbiddenError";
+        readonly message: "Forbidden.";
+        readonly uiMessage: "You do not have permission to access this resource.";
     };
     readonly 404: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "NOT_FOUND";
+        readonly name: "NotFoundError";
+        readonly message: "Not found.";
+        readonly uiMessage: "The requested resource could not be found.";
     };
     readonly 405: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "METHOD_NOT_ALLOWED";
+        readonly name: "MethodNotAllowedError";
+        readonly message: "Method not allowed.";
+        readonly uiMessage: "This action is not allowed for the requested resource.";
     };
     readonly 406: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "NOT_ACCEPTABLE";
+        readonly name: "NotAcceptableError";
+        readonly message: "Not acceptable.";
+        readonly uiMessage: "The requested format is not supported.";
     };
     readonly 407: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "PROXY_AUTHENTICATION_REQUIRED";
+        readonly name: "ProxyAuthenticationRequiredError";
+        readonly message: "Proxy authentication required.";
+        readonly uiMessage: "Proxy authentication is required to access this resource.";
     };
     readonly 408: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "REQUEST_TIMEOUT";
+        readonly name: "RequestTimeoutError";
+        readonly message: "Request timeout.";
+        readonly uiMessage: "The request took too long to complete. Please try again.";
     };
     readonly 409: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "CONFLICT";
+        readonly name: "ConflictError";
+        readonly message: "Conflict.";
+        readonly uiMessage: "The request conflicts with the current state. Please refresh and try again.";
     };
     readonly 410: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "GONE";
+        readonly name: "GoneError";
+        readonly message: "Gone.";
+        readonly uiMessage: "This resource is no longer available.";
     };
     readonly 411: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "LENGTH_REQUIRED";
+        readonly name: "LengthRequiredError";
+        readonly message: "Length required.";
+        readonly uiMessage: "The request is missing required length information.";
     };
     readonly 412: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "PRECONDITION_FAILED";
+        readonly name: "PreconditionFailedError";
+        readonly message: "Precondition failed.";
+        readonly uiMessage: "A required condition was not met. Please try again.";
     };
     readonly 413: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "PAYLOAD_TOO_LARGE";
+        readonly name: "PayloadTooLargeError";
+        readonly message: "Payload too large.";
+        readonly uiMessage: "The request is too large. Please reduce the size and try again.";
     };
     readonly 414: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "URI_TOO_LONG";
+        readonly name: "UriTooLongError";
+        readonly message: "URI too long.";
+        readonly uiMessage: "The request URL is too long.";
     };
     readonly 415: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "UNSUPPORTED_MEDIA_TYPE";
+        readonly name: "UnsupportedMediaTypeError";
+        readonly message: "Unsupported media type.";
+        readonly uiMessage: "The file type is not supported.";
     };
     readonly 416: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "RANGE_NOT_SATISFIABLE";
+        readonly name: "RangeNotSatisfiableError";
+        readonly message: "Range not satisfiable.";
+        readonly uiMessage: "The requested range cannot be satisfied.";
     };
     readonly 417: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "EXPECTATION_FAILED";
+        readonly name: "ExpectationFailedError";
+        readonly message: "Expectation failed.";
+        readonly uiMessage: "The server cannot meet the requirements of the request.";
     };
     readonly 418: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "IM_A_TEAPOT";
+        readonly name: "ImATeapotError";
+        readonly message: "I'm a teapot.";
+        readonly uiMessage: "I'm a teapot and cannot brew coffee.";
     };
     readonly 422: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "UNPROCESSABLE_ENTITY";
+        readonly name: "UnprocessableEntityError";
+        readonly message: "Unprocessable entity.";
+        readonly uiMessage: "The request contains invalid data. Please check your input.";
     };
     readonly 423: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "LOCKED";
+        readonly name: "LockedError";
+        readonly message: "Locked.";
+        readonly uiMessage: "This resource is locked and cannot be modified.";
     };
     readonly 424: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "FAILED_DEPENDENCY";
+        readonly name: "FailedDependencyError";
+        readonly message: "Failed dependency.";
+        readonly uiMessage: "The request failed due to a dependency error.";
     };
     readonly 425: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "TOO_EARLY";
+        readonly name: "TooEarlyError";
+        readonly message: "Too early.";
+        readonly uiMessage: "The request was sent too early. Please try again later.";
     };
     readonly 426: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "UPGRADE_REQUIRED";
+        readonly name: "UpgradeRequiredError";
+        readonly message: "Upgrade required.";
+        readonly uiMessage: "Please upgrade to continue using this service.";
     };
     readonly 428: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "PRECONDITION_REQUIRED";
+        readonly name: "PreconditionRequiredError";
+        readonly message: "Precondition required.";
+        readonly uiMessage: "Required conditions are missing from the request.";
     };
     readonly 429: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "TOO_MANY_REQUESTS";
+        readonly name: "TooManyRequestsError";
+        readonly message: "Too many requests.";
+        readonly uiMessage: "You have made too many requests. Please wait and try again.";
     };
     readonly 431: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "REQUEST_HEADER_FIELDS_TOO_LARGE";
+        readonly name: "RequestHeaderFieldsTooLargeError";
+        readonly message: "Request header fields too large.";
+        readonly uiMessage: "The request headers are too large.";
     };
     readonly 451: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "UNAVAILABLE_FOR_LEGAL_REASONS";
+        readonly name: "UnavailableForLegalReasonsError";
+        readonly message: "Unavailable for legal reasons.";
+        readonly uiMessage: "This content is unavailable for legal reasons.";
     };
     readonly 500: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "INTERNAL_SERVER_ERROR";
+        readonly name: "InternalServerError";
+        readonly message: "Internal server error.";
+        readonly uiMessage: "An unexpected error occurred. Please try again later.";
     };
     readonly 501: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "NOT_IMPLEMENTED";
+        readonly name: "NotImplementedError";
+        readonly message: "Not implemented.";
+        readonly uiMessage: "This feature is not yet available.";
     };
     readonly 502: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "BAD_GATEWAY";
+        readonly name: "BadGatewayError";
+        readonly message: "Bad gateway.";
+        readonly uiMessage: "Unable to connect to the server. Please try again later.";
     };
     readonly 503: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "SERVICE_UNAVAILABLE";
+        readonly name: "ServiceUnavailableError";
+        readonly message: "Service unavailable.";
+        readonly uiMessage: "The service is temporarily unavailable. Please try again later.";
     };
     readonly 504: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "GATEWAY_TIMEOUT";
+        readonly name: "GatewayTimeoutError";
+        readonly message: "Gateway timeout.";
+        readonly uiMessage: "The server took too long to respond. Please try again.";
     };
     readonly 505: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "HTTP_VERSION_NOT_SUPPORTED";
+        readonly name: "HttpVersionNotSupportedError";
+        readonly message: "HTTP version not supported.";
+        readonly uiMessage: "Your browser version is not supported.";
     };
     readonly 506: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "VARIANT_ALSO_NEGOTIATES";
+        readonly name: "VariantAlsoNegotiatesError";
+        readonly message: "Variant also negotiates.";
+        readonly uiMessage: "The server has an internal configuration error.";
     };
     readonly 507: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "INSUFFICIENT_STORAGE";
+        readonly name: "InsufficientStorageError";
+        readonly message: "Insufficient storage.";
+        readonly uiMessage: "The server has insufficient storage to complete the request.";
     };
     readonly 508: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "LOOP_DETECTED";
+        readonly name: "LoopDetectedError";
+        readonly message: "Loop detected.";
+        readonly uiMessage: "The server detected an infinite loop.";
     };
     readonly 510: {
-        code: string;
-        name: string;
-        message: string;
-        uiMessage: string;
-        metadata: {
-            status: number;
-        };
+        readonly code: "NOT_EXTENDED";
+        readonly name: "NotExtendedError";
+        readonly message: "Not extended.";
+        readonly uiMessage: "Additional extensions are required.";
     };
     readonly 511: {
-        code: string;
+        readonly code: "NETWORK_AUTHENTICATION_REQUIRED";
+        readonly name: "NetworkAuthenticationRequiredError";
+        readonly message: "Network authentication required.";
+        readonly uiMessage: "Network authentication is required to access this resource.";
+    };
+};
+/**
+ * Valid HTTP status codes for HTTPErrorX.create()
+ * Derived from the presets object. Provides autocomplete for known codes
+ * while allowing any number for flexibility.
+ */
+type HTTPErrorXPresetKey = keyof typeof httpPresets | ErrorXBasePresetKey;
+/**
+ * Metadata type for HTTP errors.
+ * Provides context about the HTTP request that failed.
+ *
+ * @public
+ */
+type HTTPErrorXMetadata = {
+    /** The endpoint/URL that was requested */
+    endpoint?: string;
+    /** The HTTP method used (GET, POST, etc.) */
+    method?: string;
+    /** Additional metadata */
+    [key: string]: unknown;
+};
+/**
+ * HTTP Error class with presets for all standard HTTP status codes.
+ *
+ * Provides a type-safe, ergonomic way to create HTTP errors with:
+ * - Numeric status code presets (400, 401, 404, 500, etc.)
+ * - Automatic httpStatus from preset key
+ * - Full `instanceof` support
+ * - Typed metadata for HTTP context
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with status code
+ * throw HTTPErrorX.create(404)
+ * throw HTTPErrorX.create(401)
+ * throw HTTPErrorX.create(500)
+ *
+ * // With custom message
+ * throw HTTPErrorX.create(404, { message: 'User not found' })
+ *
+ * // With metadata
+ * throw HTTPErrorX.create(401, {
+ *   message: 'Invalid token',
+ *   metadata: { endpoint: '/api/users', method: 'GET' }
+ * })
+ *
+ * // With error chaining
+ * try {
+ *   await fetchUser(id)
+ * } catch (err) {
+ *   throw HTTPErrorX.create(500, { cause: err })
+ * }
+ *
+ * // Just overrides (uses default 500)
+ * throw HTTPErrorX.create({ message: 'Something went wrong' })
+ *
+ * // instanceof checks
+ * if (error instanceof HTTPErrorX) {
+ *   console.log(error.httpStatus) // 404
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class HTTPErrorX extends ErrorX<HTTPErrorXMetadata> {
+    /**
+     * HTTP status code presets for all standard codes.
+     * Keys are numeric status codes (400, 401, 404, 500, etc.)
+     */
+    static presets: {
+        readonly 400: {
+            readonly code: "BAD_REQUEST";
+            readonly name: "BadRequestError";
+            readonly message: "Bad request.";
+            readonly uiMessage: "The request could not be processed. Please check your input and try again.";
+        };
+        readonly 401: {
+            readonly code: "UNAUTHORIZED";
+            readonly name: "UnauthorizedError";
+            readonly message: "Unauthorized.";
+            readonly uiMessage: "Authentication required. Please log in to continue.";
+        };
+        readonly 402: {
+            readonly code: "PAYMENT_REQUIRED";
+            readonly name: "PaymentRequiredError";
+            readonly message: "Payment required.";
+            readonly uiMessage: "Payment is required to access this resource.";
+        };
+        readonly 403: {
+            readonly code: "FORBIDDEN";
+            readonly name: "ForbiddenError";
+            readonly message: "Forbidden.";
+            readonly uiMessage: "You do not have permission to access this resource.";
+        };
+        readonly 404: {
+            readonly code: "NOT_FOUND";
+            readonly name: "NotFoundError";
+            readonly message: "Not found.";
+            readonly uiMessage: "The requested resource could not be found.";
+        };
+        readonly 405: {
+            readonly code: "METHOD_NOT_ALLOWED";
+            readonly name: "MethodNotAllowedError";
+            readonly message: "Method not allowed.";
+            readonly uiMessage: "This action is not allowed for the requested resource.";
+        };
+        readonly 406: {
+            readonly code: "NOT_ACCEPTABLE";
+            readonly name: "NotAcceptableError";
+            readonly message: "Not acceptable.";
+            readonly uiMessage: "The requested format is not supported.";
+        };
+        readonly 407: {
+            readonly code: "PROXY_AUTHENTICATION_REQUIRED";
+            readonly name: "ProxyAuthenticationRequiredError";
+            readonly message: "Proxy authentication required.";
+            readonly uiMessage: "Proxy authentication is required to access this resource.";
+        };
+        readonly 408: {
+            readonly code: "REQUEST_TIMEOUT";
+            readonly name: "RequestTimeoutError";
+            readonly message: "Request timeout.";
+            readonly uiMessage: "The request took too long to complete. Please try again.";
+        };
+        readonly 409: {
+            readonly code: "CONFLICT";
+            readonly name: "ConflictError";
+            readonly message: "Conflict.";
+            readonly uiMessage: "The request conflicts with the current state. Please refresh and try again.";
+        };
+        readonly 410: {
+            readonly code: "GONE";
+            readonly name: "GoneError";
+            readonly message: "Gone.";
+            readonly uiMessage: "This resource is no longer available.";
+        };
+        readonly 411: {
+            readonly code: "LENGTH_REQUIRED";
+            readonly name: "LengthRequiredError";
+            readonly message: "Length required.";
+            readonly uiMessage: "The request is missing required length information.";
+        };
+        readonly 412: {
+            readonly code: "PRECONDITION_FAILED";
+            readonly name: "PreconditionFailedError";
+            readonly message: "Precondition failed.";
+            readonly uiMessage: "A required condition was not met. Please try again.";
+        };
+        readonly 413: {
+            readonly code: "PAYLOAD_TOO_LARGE";
+            readonly name: "PayloadTooLargeError";
+            readonly message: "Payload too large.";
+            readonly uiMessage: "The request is too large. Please reduce the size and try again.";
+        };
+        readonly 414: {
+            readonly code: "URI_TOO_LONG";
+            readonly name: "UriTooLongError";
+            readonly message: "URI too long.";
+            readonly uiMessage: "The request URL is too long.";
+        };
+        readonly 415: {
+            readonly code: "UNSUPPORTED_MEDIA_TYPE";
+            readonly name: "UnsupportedMediaTypeError";
+            readonly message: "Unsupported media type.";
+            readonly uiMessage: "The file type is not supported.";
+        };
+        readonly 416: {
+            readonly code: "RANGE_NOT_SATISFIABLE";
+            readonly name: "RangeNotSatisfiableError";
+            readonly message: "Range not satisfiable.";
+            readonly uiMessage: "The requested range cannot be satisfied.";
+        };
+        readonly 417: {
+            readonly code: "EXPECTATION_FAILED";
+            readonly name: "ExpectationFailedError";
+            readonly message: "Expectation failed.";
+            readonly uiMessage: "The server cannot meet the requirements of the request.";
+        };
+        readonly 418: {
+            readonly code: "IM_A_TEAPOT";
+            readonly name: "ImATeapotError";
+            readonly message: "I'm a teapot.";
+            readonly uiMessage: "I'm a teapot and cannot brew coffee.";
+        };
+        readonly 422: {
+            readonly code: "UNPROCESSABLE_ENTITY";
+            readonly name: "UnprocessableEntityError";
+            readonly message: "Unprocessable entity.";
+            readonly uiMessage: "The request contains invalid data. Please check your input.";
+        };
+        readonly 423: {
+            readonly code: "LOCKED";
+            readonly name: "LockedError";
+            readonly message: "Locked.";
+            readonly uiMessage: "This resource is locked and cannot be modified.";
+        };
+        readonly 424: {
+            readonly code: "FAILED_DEPENDENCY";
+            readonly name: "FailedDependencyError";
+            readonly message: "Failed dependency.";
+            readonly uiMessage: "The request failed due to a dependency error.";
+        };
+        readonly 425: {
+            readonly code: "TOO_EARLY";
+            readonly name: "TooEarlyError";
+            readonly message: "Too early.";
+            readonly uiMessage: "The request was sent too early. Please try again later.";
+        };
+        readonly 426: {
+            readonly code: "UPGRADE_REQUIRED";
+            readonly name: "UpgradeRequiredError";
+            readonly message: "Upgrade required.";
+            readonly uiMessage: "Please upgrade to continue using this service.";
+        };
+        readonly 428: {
+            readonly code: "PRECONDITION_REQUIRED";
+            readonly name: "PreconditionRequiredError";
+            readonly message: "Precondition required.";
+            readonly uiMessage: "Required conditions are missing from the request.";
+        };
+        readonly 429: {
+            readonly code: "TOO_MANY_REQUESTS";
+            readonly name: "TooManyRequestsError";
+            readonly message: "Too many requests.";
+            readonly uiMessage: "You have made too many requests. Please wait and try again.";
+        };
+        readonly 431: {
+            readonly code: "REQUEST_HEADER_FIELDS_TOO_LARGE";
+            readonly name: "RequestHeaderFieldsTooLargeError";
+            readonly message: "Request header fields too large.";
+            readonly uiMessage: "The request headers are too large.";
+        };
+        readonly 451: {
+            readonly code: "UNAVAILABLE_FOR_LEGAL_REASONS";
+            readonly name: "UnavailableForLegalReasonsError";
+            readonly message: "Unavailable for legal reasons.";
+            readonly uiMessage: "This content is unavailable for legal reasons.";
+        };
+        readonly 500: {
+            readonly code: "INTERNAL_SERVER_ERROR";
+            readonly name: "InternalServerError";
+            readonly message: "Internal server error.";
+            readonly uiMessage: "An unexpected error occurred. Please try again later.";
+        };
+        readonly 501: {
+            readonly code: "NOT_IMPLEMENTED";
+            readonly name: "NotImplementedError";
+            readonly message: "Not implemented.";
+            readonly uiMessage: "This feature is not yet available.";
+        };
+        readonly 502: {
+            readonly code: "BAD_GATEWAY";
+            readonly name: "BadGatewayError";
+            readonly message: "Bad gateway.";
+            readonly uiMessage: "Unable to connect to the server. Please try again later.";
+        };
+        readonly 503: {
+            readonly code: "SERVICE_UNAVAILABLE";
+            readonly name: "ServiceUnavailableError";
+            readonly message: "Service unavailable.";
+            readonly uiMessage: "The service is temporarily unavailable. Please try again later.";
+        };
+        readonly 504: {
+            readonly code: "GATEWAY_TIMEOUT";
+            readonly name: "GatewayTimeoutError";
+            readonly message: "Gateway timeout.";
+            readonly uiMessage: "The server took too long to respond. Please try again.";
+        };
+        readonly 505: {
+            readonly code: "HTTP_VERSION_NOT_SUPPORTED";
+            readonly name: "HttpVersionNotSupportedError";
+            readonly message: "HTTP version not supported.";
+            readonly uiMessage: "Your browser version is not supported.";
+        };
+        readonly 506: {
+            readonly code: "VARIANT_ALSO_NEGOTIATES";
+            readonly name: "VariantAlsoNegotiatesError";
+            readonly message: "Variant also negotiates.";
+            readonly uiMessage: "The server has an internal configuration error.";
+        };
+        readonly 507: {
+            readonly code: "INSUFFICIENT_STORAGE";
+            readonly name: "InsufficientStorageError";
+            readonly message: "Insufficient storage.";
+            readonly uiMessage: "The server has insufficient storage to complete the request.";
+        };
+        readonly 508: {
+            readonly code: "LOOP_DETECTED";
+            readonly name: "LoopDetectedError";
+            readonly message: "Loop detected.";
+            readonly uiMessage: "The server detected an infinite loop.";
+        };
+        readonly 510: {
+            readonly code: "NOT_EXTENDED";
+            readonly name: "NotExtendedError";
+            readonly message: "Not extended.";
+            readonly uiMessage: "Additional extensions are required.";
+        };
+        readonly 511: {
+            readonly code: "NETWORK_AUTHENTICATION_REQUIRED";
+            readonly name: "NetworkAuthenticationRequiredError";
+            readonly message: "Network authentication required.";
+            readonly uiMessage: "Network authentication is required to access this resource.";
+        };
+    };
+    /** Default to 500 Internal Server Error when no preset specified */
+    static defaultPreset: number;
+    /** Default httpStatus for all HTTPErrorXs */
+    static defaults: {
+        httpStatus: number;
+    };
+    /**
+     * Transform that automatically sets httpStatus from the preset key.
+     * Only sets httpStatus from presetKey if it matches a known preset.
+     */
+    static transform: ErrorXTransform<HTTPErrorXMetadata>;
+    /**
+     * Creates an HTTPErrorX from a status code preset.
+     *
+     * @param statusCode - HTTP status code (provides autocomplete for standard codes)
+     * @param overrides - Optional overrides for the preset values
+     * @returns HTTPErrorX instance
+     */
+    static create(statusCode?: HTTPErrorXPresetKey, overrides?: Partial<ErrorXOptions<HTTPErrorXMetadata>>): HTTPErrorX;
+    static create(overrides?: Partial<ErrorXOptions<HTTPErrorXMetadata>>): HTTPErrorX;
+}
+
+/**
+ * Zod issue structure for type compatibility.
+ * Matches the shape of Zod's ZodIssue type.
+ *
+ * @public
+ */
+type ZodIssue = {
+    code: string;
+    path: (string | number)[];
+    message: string;
+    expected?: string;
+    received?: string;
+    minimum?: number;
+    maximum?: number;
+    inclusive?: boolean;
+    exact?: boolean;
+    type?: string;
+};
+/**
+ * Metadata type for validation errors.
+ * Designed to capture all relevant Zod validation context.
+ *
+ * @public
+ */
+type ValidationErrorXMetadata = {
+    /** The field that failed validation (dot-notation path) */
+    field?: string;
+    /** The full path to the field (for nested objects) */
+    path?: (string | number)[];
+    /** The Zod issue code (e.g., 'invalid_type', 'too_small') */
+    zodCode?: string;
+    /** The expected type or value */
+    expected?: string;
+    /** The received value (sanitized for safety) */
+    received?: string;
+    /** Total number of validation issues */
+    issueCount?: number;
+    /** All Zod issues (for multi-error handling) */
+    issues?: ZodIssue[];
+};
+/**
+ * Validation Error class designed for Zod integration.
+ *
+ * This class demonstrates how to map external library data (Zod) to ErrorX.
+ * Instead of using presets, it dynamically creates errors from Zod's validation output.
+ *
+ * Key features:
+ * - `fromZodError()` - Primary factory method for Zod integration
+ * - Dynamic code mapping from Zod issue codes
+ * - Full `instanceof` support for catch blocks
+ * - Typed metadata capturing all Zod context
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod'
+ * import { ValidationErrorX } from 'error-x'
+ *
+ * const userSchema = z.object({
+ *   email: z.string().email(),
+ *   age: z.number().min(18),
+ * })
+ *
+ * // Primary usage: fromZodError()
+ * try {
+ *   userSchema.parse({ email: 'invalid', age: 15 })
+ * } catch (err) {
+ *   if (err instanceof z.ZodError) {
+ *     throw ValidationErrorX.fromZodError(err)
+ *     // → code: 'VALIDATION_INVALID_STRING'
+ *     // → message: 'Invalid email'
+ *     // → metadata.field: 'email'
+ *     // → metadata.zodCode: 'invalid_string'
+ *   }
+ * }
+ *
+ * // With overrides
+ * ValidationErrorX.fromZodError(zodError, {
+ *   uiMessage: 'Please check your input',
+ *   httpStatus: 422,
+ * })
+ *
+ * // Direct creation (without Zod)
+ * ValidationErrorX.create({
+ *   message: 'Invalid email format',
+ *   code: 'INVALID_EMAIL',
+ *   metadata: { field: 'email' }
+ * })
+ *
+ * // instanceof in catch blocks
+ * try {
+ *   await processRequest(data)
+ * } catch (err) {
+ *   if (err instanceof ValidationErrorX) {
+ *     return res.status(err.httpStatus).json({
+ *       error: err.code,
+ *       message: err.uiMessage,
+ *       field: err.metadata?.field,
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class ValidationErrorX extends ErrorX<ValidationErrorXMetadata> {
+    /** Default httpStatus for validation errors (400 = bad request) */
+    static defaults: {
+        httpStatus: number;
         name: string;
+        code: string;
         message: string;
         uiMessage: string;
-        metadata: {
-            status: number;
-        };
     };
-};
+    /**
+     * Transform that maps Zod issue codes to VALIDATION_ prefixed codes.
+     * Converts Zod's snake_case codes to SCREAMING_SNAKE_CASE.
+     */
+    static transform: ErrorXTransform<ValidationErrorXMetadata>;
+    /**
+     * Creates a ValidationErrorX from a Zod error.
+     *
+     * Maps Zod's error structure to ErrorX:
+     * - Uses first issue's message as the error message
+     * - Converts Zod issue code to ErrorX code (e.g., 'invalid_type' → 'VALIDATION_INVALID_TYPE')
+     * - Captures all issues in metadata for multi-error handling
+     *
+     * @param zodError - The Zod error object (or any object with `issues` array)
+     * @param overrides - Optional overrides for any ErrorX options
+     * @returns ValidationErrorX instance
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * try {
+     *   schema.parse(data)
+     * } catch (err) {
+     *   if (err instanceof ZodError) {
+     *     throw ValidationErrorX.fromZodError(err)
+     *   }
+     * }
+     *
+     * // With custom uiMessage
+     * ValidationErrorX.fromZodError(zodError, {
+     *   uiMessage: 'Please fix the form errors',
+     * })
+     *
+     * // Access all issues
+     * const error = ValidationErrorX.fromZodError(zodError)
+     * error.metadata?.issues?.forEach(issue => {
+     *   console.log(`${issue.path.join('.')}: ${issue.message}`)
+     * })
+     * ```
+     */
+    static fromZodError(zodError: {
+        issues: ZodIssue[];
+    }, overrides?: Partial<ErrorXOptions<ValidationErrorXMetadata>>): ValidationErrorX;
+    /**
+     * Creates a ValidationErrorX for a specific field.
+     * Convenience method for manual validation errors.
+     *
+     * @param field - The field name that failed validation
+     * @param message - The error message
+     * @param options - Additional options
+     * @returns ValidationErrorX instance
+     *
+     * @example
+     * ```typescript
+     * // Simple field error
+     * throw ValidationErrorX.forField('email', 'Invalid email format')
+     *
+     * // With code
+     * throw ValidationErrorX.forField('age', 'Must be 18 or older', {
+     *   code: 'TOO_YOUNG',
+     * })
+     * ```
+     */
+    static forField(field: string, message: string, options?: Partial<ErrorXOptions<ValidationErrorXMetadata>>): ValidationErrorX;
+}
 
-export { ErrorX, type ErrorXCause, type ErrorXConfig, type ErrorXMetadata, type ErrorXOptions, type ErrorXSerialized, http };
+export { type DBErrorXPresetKey as DBErrorPreset, DBErrorX, type DBErrorXMetadata, ErrorX, type ErrorXCause, type ErrorXConfig, type ErrorXMetadata, type ErrorXOptions, type ErrorXSerialized, type ErrorXTransform, type ErrorXTransformContext, HTTPErrorX, type HTTPErrorXMetadata, type HTTPErrorXPresetKey as HTTPStatusCode, ValidationErrorX, type ValidationErrorXMetadata, type ZodIssue };