@bombillazo/error-x 0.5.1 → 0.6.0

package/dist/index.d.cts

@@ -58,8 +58,6 @@ type ErrorXOptions<TMetadata extends ErrorXMetadata = ErrorXMetadata> = {
     name?: string;
     /** Error identifier code (auto-generated from name if not provided) */
     code?: string | number;
-    /** User-friendly message for UI display */
-    uiMessage?: string | undefined;
     /** Original error that caused this error (preserves error chain, will be converted to ErrorXSnapshot format) */
     cause?: unknown;
     /** Additional context and debugging information */
@@ -82,51 +80,155 @@ type ErrorXSnapshot = {
     stack?: string;
 };
 /**
- * Context passed to the transform function when creating errors via `.create()`.
- * Contains information about the preset being used.
+ * Type representing valid preset keys for error creation.
+ * Allows both string and number keys while preventing accidental misuse.
  *
  * @public
  */
-type ErrorXTransformContext = {
-    /** The preset key used (if any) */
-    presetKey: string | number | undefined;
-};
+type ErrorXBasePresetKey = (number & {}) | (string & {});
+
 /**
- * Transform function signature for custom error classes.
- * Transforms options after merge but before instantiation.
+ * Base configuration properties provided by error-x.
+ * Users extend this with their custom properties via ErrorXResolverConfig.
  *
  * @public
  */
-type ErrorXTransform<TMetadata extends ErrorXMetadata = ErrorXMetadata> = (opts: ErrorXOptions<ErrorXMetadata>, ctx: ErrorXTransformContext) => ErrorXOptions<TMetadata>;
+type ErrorXBaseConfig = {
+    /** i18n namespace for translation key resolution (e.g., 'errors.api') */
+    namespace: string;
+    /** Path appended to docs base URL (e.g., '/api') */
+    docsPath?: string;
+    /** Static UI message - overrides i18n at preset level, fallback otherwise */
+    uiMessage?: string;
+};
 /**
- * JSON-serializable representation of an ErrorX instance.
- * Used for transmitting errors over network or storing in databases.
+ * Type helper combining ErrorXBaseConfig with user's custom config properties.
  *
  * @example
  * ```typescript
- * const serialized: ErrorXSerialized = {
- *   name: 'AuthError',
- *   message: 'Authentication failed.',
- *   code: 'AUTH_FAILED',
- *   uiMessage: 'Please check your credentials',
- *   stack: 'Error: Authentication failed.\n    at login (auth.ts:42:15)',
- *   metadata: { userId: 123, loginAttempt: 3 },
- *   timestamp: 1705315845123,
- *   httpStatus: 401,
- *   original: {
- *     name: 'NetworkError',
- *     message: 'Request timeout.',
- *     stack: '...'
- *   },
- *   chain: [
- *     { name: 'AuthError', message: 'Authentication failed.' },
- *     { name: 'NetworkError', message: 'Request timeout.' }
- *   ]
- * }
+ * type MyConfig = ErrorXResolverConfig<{
+ *   severity: 'error' | 'warning' | 'info';
+ *   retryable: boolean;
+ * }>;
  * ```
  *
  * @public
  */
+type ErrorXResolverConfig<TCustom extends Record<string, unknown> = Record<string, unknown>> = ErrorXBaseConfig & TCustom;
+/**
+ * Context object passed to the onResolve callback.
+ * Contains computed values and merged config for the error.
+ *
+ * @public
+ */
+type ResolveContext<TConfig extends ErrorXBaseConfig = ErrorXBaseConfig> = {
+    /** Resolved UI message (from i18n or static config) */
+    uiMessage: string | undefined;
+    /** Full documentation URL */
+    docsUrl: string;
+    /** The resolved i18n key (e.g., 'errors.api.AUTH_EXPIRED') */
+    i18nKey: string;
+    /** The error type returned by onResolveType callback */
+    errorType: string;
+    /** Merged config for this error (defaults + type + preset) */
+    config: TConfig;
+};
+/**
+ * i18n configuration for the resolver.
+ *
+ * @public
+ */
+type ErrorXResolverI18nConfig = {
+    /**
+     * User-provided translation function.
+     * Receives the i18n key and optional interpolation params (from error.metadata).
+     *
+     * @example
+     * ```typescript
+     * resolver: (key, params) => i18next.t(key, params)
+     * ```
+     */
+    resolver: (key: string, params?: Record<string, unknown>) => string;
+    /**
+     * Template for building translation keys.
+     * Available placeholders: {namespace}, {code}, {name}, {errorType}
+     * @default '{namespace}.{code}'
+     */
+    keyTemplate?: string;
+};
+/**
+ * Documentation configuration for the resolver.
+ *
+ * @public
+ */
+type ErrorXResolverDocsConfig = {
+    /**
+     * Base URL for documentation.
+     * @default '' (empty string)
+     */
+    baseUrl?: string;
+};
+/**
+ * Per-error-type configuration with optional preset overrides.
+ *
+ * @public
+ */
+type ErrorXResolverTypeConfig<TConfig extends ErrorXBaseConfig = ErrorXBaseConfig> = Omit<TConfig, 'presets'> & {
+    /** Per-error-code overrides within this type */
+    presets?: {
+        [code: string]: Partial<ErrorXBaseConfig> & Partial<Omit<TConfig, keyof ErrorXBaseConfig>>;
+    };
+};
+/**
+ * Full configuration options for ErrorXResolver.
+ *
+ * @public
+ */
+type ErrorXResolverOptions<TConfig extends ErrorXBaseConfig = ErrorXBaseConfig, TResult = ResolveContext<TConfig>> = {
+    /** Optional i18n configuration. If not provided, relies on static uiMessage values. */
+    i18n?: ErrorXResolverI18nConfig;
+    /** Optional documentation URL configuration. */
+    docs?: ErrorXResolverDocsConfig;
+    /**
+     * Callback to determine the error type key.
+     * The returned string is used to look up config in the configs object.
+     *
+     * @example
+     * ```typescript
+     * onResolveType: (error) => {
+     *   if (error instanceof APIErrorX) return 'api';
+     *   if (error.code.startsWith('DB_')) return 'database';
+     *   return 'general';
+     * }
+     * ```
+     */
+    onResolveType: (error: ErrorX) => string;
+    /**
+     * Optional callback to customize the resolve output.
+     * If not provided, resolve() returns the ResolveContext directly.
+     *
+     * @example
+     * ```typescript
+     * onResolve: (error, context) => ({
+     *   message: context.uiMessage,
+     *   docs: context.docsUrl,
+     *   severity: context.config.severity,
+     * })
+     * ```
+     */
+    onResolve?: (error: ErrorX, context: ResolveContext<TConfig>) => TResult;
+    /** Default config values (fallback for all error types) */
+    defaults?: Partial<ErrorXBaseConfig> & Partial<Omit<TConfig, keyof ErrorXBaseConfig>>;
+    /** Per-error-type configurations (partial configs get merged with defaults) */
+    configs: Record<string, Partial<ErrorXResolverTypeConfig<TConfig>>>;
+};
+
+/**
+ * JSON-serializable representation of an ErrorX instance.
+ * Used for transmitting errors over network or storing in databases.
+ *
+ * @public
+ */
 type ErrorXSerialized = {
     /** Error type/name */
     name: string;
@@ -134,8 +236,6 @@ type ErrorXSerialized = {
     message: string;
     /** Error identifier code */
     code: string;
-    /** User-friendly message for UI display */
-    uiMessage: string | undefined;
     /** Stack trace (optional) */
     stack?: string;
     /** Additional context and debugging information */
@@ -149,13 +249,24 @@ type ErrorXSerialized = {
     /** Serialized error chain timeline (this error and all ancestors) */
     chain?: ErrorXSerialized[];
 };
+
 /**
- * Type representing valid preset keys for error creation.
- * Allows both string and number keys while preventing accidental misuse.
+ * Context passed to the transform function when creating errors via `.create()`.
+ * Contains information about the preset being used.
  *
  * @public
  */
-type ErrorXBasePresetKey = (number & {}) | (string & {});
+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>;
 
 /**
  * Configuration interface for ErrorX global settings
@@ -194,7 +305,6 @@ interface ErrorXConfig {
  *   message: 'User authentication failed',
  *   name: 'AuthError',
  *   code: 'AUTH_FAILED',
- *   uiMessage: 'Please check your credentials',
  *   metadata: { userId: 123, loginAttempt: 3 }
  * })
  *
@@ -214,8 +324,6 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
     private static _config;
     /** Error identifier code, auto-generated from name if not provided */
     code: string;
-    /** User-friendly message suitable for display in UI */
-    uiMessage: string | undefined;
     /** Additional context and metadata associated with the error */
     metadata: TMetadata | undefined;
     /** Unix epoch timestamp (milliseconds) when the error was created */
@@ -259,7 +367,6 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      *   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 }
      * })
      *
@@ -505,7 +612,6 @@ declare class ErrorX<TMetadata extends ErrorXMetadata = ErrorXMetadata> extends
      *   name: 'DatabaseError',
      *   message: 'Connection failed.',
      *   code: 'DB_CONN_FAILED',
-     *   uiMessage: 'Database is temporarily unavailable',
      *   metadata: { host: 'localhost' },
      *   timestamp: 1705315845123
      * }
@@ -571,99 +677,89 @@ declare const dbPresets: {
         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.";
     };
 };
+/**
+ * User-friendly messages for database error presets.
+ * Keyed by preset name.
+ */
+declare const dbErrorUiMessages: Record<keyof typeof dbPresets, string>;
 /**
  * Valid preset keys for DBErrorX.create()
  * Derived from the presets object. Provides autocomplete for known presets
@@ -745,97 +841,82 @@ declare class DBErrorX extends ErrorX<DBErrorXMetadata> {
             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 */
@@ -868,237 +949,203 @@ declare const httpPresets: {
         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.";
     };
 };
+/**
+ * User-friendly messages for HTTP error presets.
+ * Keyed by HTTP status code.
+ */
+declare const httpErrorUiMessages: Record<keyof typeof httpPresets, string>;
 /**
  * Valid HTTP status codes for HTTPErrorX.create()
  * Derived from the presets object. Provides autocomplete for known codes
@@ -1172,235 +1219,196 @@ declare class HTTPErrorX extends ErrorX<HTTPErrorXMetadata> {
             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 */
@@ -1465,6 +1473,10 @@ type ValidationErrorXMetadata = {
     /** All Zod issues (for multi-error handling) */
     issues?: ZodIssue[];
 };
+/**
+ * Default user-friendly message for validation errors.
+ */
+declare const validationErrorUiMessage = "The provided input is invalid. Please check your data.";
 /**
  * Validation Error class designed for Zod integration.
  *
@@ -1502,7 +1514,6 @@ type ValidationErrorXMetadata = {
  *
  * // With overrides
  * ValidationErrorX.fromZodError(zodError, {
- *   uiMessage: 'Please check your input',
  *   httpStatus: 422,
  * })
  *
@@ -1520,7 +1531,7 @@ type ValidationErrorXMetadata = {
  *   if (err instanceof ValidationErrorX) {
  *     return res.status(err.httpStatus).json({
  *       error: err.code,
- *       message: err.uiMessage,
+ *       message: err.message,
  *       field: err.metadata?.field,
  *     })
  *   }
@@ -1536,7 +1547,6 @@ declare class ValidationErrorX extends ErrorX<ValidationErrorXMetadata> {
         name: string;
         code: string;
         message: string;
-        uiMessage: string;
     };
     /**
      * Transform that maps Zod issue codes to VALIDATION_ prefixed codes.
@@ -1566,9 +1576,9 @@ declare class ValidationErrorX extends ErrorX<ValidationErrorXMetadata> {
      *   }
      * }
      *
-     * // With custom uiMessage
+     * // With custom message
      * ValidationErrorX.fromZodError(zodError, {
-     *   uiMessage: 'Please fix the form errors',
+     *   message: 'Please fix the form errors',
      * })
      *
      * // Access all issues
@@ -1604,4 +1614,60 @@ declare class ValidationErrorX extends ErrorX<ValidationErrorXMetadata> {
     static forField(field: string, message: string, options?: Partial<ErrorXOptions<ValidationErrorXMetadata>>): ValidationErrorX;
 }
 
-export { type DBErrorXPresetKey as DBErrorPreset, DBErrorX, type DBErrorXMetadata, ErrorX, type ErrorXConfig, type ErrorXMetadata, type ErrorXOptions, type ErrorXSerialized, type ErrorXSnapshot, type ErrorXTransform, type ErrorXTransformContext, HTTPErrorX, type HTTPErrorXMetadata, type HTTPErrorXPresetKey as HTTPStatusCode, ValidationErrorX, type ValidationErrorXMetadata, type ZodIssue };
+/**
+ * Resolves ErrorX errors to enhanced presentation objects.
+ * Supports i18n translations, documentation URLs, and custom properties.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new ErrorXResolver({
+ *   i18n: { resolver: i18next.t },
+ *   docs: { baseUrl: 'https://docs.example.com' },
+ *   onResolveType: (error) => error.code.startsWith('API_') ? 'api' : 'general',
+ *   configs: {
+ *     api: { namespace: 'errors.api', docsPath: '/api' },
+ *     general: { namespace: 'errors' },
+ *   },
+ * });
+ *
+ * const result = resolver.resolve(error, 'es');
+ * ```
+ *
+ * @public
+ */
+declare class ErrorXResolver<TConfig extends ErrorXBaseConfig = ErrorXBaseConfig, TResult = ResolveContext<TConfig>> {
+    private readonly options;
+    private readonly defaultKeyTemplate;
+    constructor(options: ErrorXResolverOptions<TConfig, TResult>);
+    /**
+     * Resolves an error to its enhanced representation.
+     *
+     * @param error - The ErrorX instance to resolve
+     * @param _locale - Optional locale for i18n (passed to resolver function)
+     * @returns The resolved result (ResolveContext or custom TResult)
+     */
+    resolve(error: ErrorX, _locale?: string): TResult;
+    /**
+     * Merges config from defaults → type → preset
+     */
+    private mergeConfig;
+    /**
+     * Builds the i18n key from template
+     */
+    private buildI18nKey;
+    /**
+     * Resolves uiMessage following the priority order:
+     * 1. presets[code].uiMessage (already merged into config if from preset)
+     * 2. i18n resolver result (if configured)
+     * 3. configs[errorType].uiMessage (fallback)
+     * 4. defaults.uiMessage (fallback)
+     * 5. undefined
+     */
+    private resolveUiMessage;
+    /**
+     * Builds the full documentation URL
+     */
+    private buildDocsUrl;
+}
+
+export { type DBErrorXPresetKey as DBErrorPreset, DBErrorX, type DBErrorXMetadata, ErrorX, type ErrorXBaseConfig, type ErrorXConfig, type ErrorXMetadata, type ErrorXOptions, ErrorXResolver, type ErrorXResolverConfig, type ErrorXResolverDocsConfig, type ErrorXResolverI18nConfig, type ErrorXResolverOptions, type ErrorXResolverTypeConfig, type ErrorXSerialized, type ErrorXSnapshot, type ErrorXTransform, type ErrorXTransformContext, HTTPErrorX, type HTTPErrorXMetadata, type HTTPErrorXPresetKey as HTTPStatusCode, type ResolveContext, ValidationErrorX, type ValidationErrorXMetadata, type ZodIssue, dbErrorUiMessages, httpErrorUiMessages, validationErrorUiMessage };