@bombillazo/error-x 0.5.0 → 0.6.0

package/README.md

@@ -18,6 +18,7 @@ A smart, isomorphic, and type-safe error library for TypeScript applications. Pr
 - **Custom metadata** with type-safe generics for additional context
 - **Global configuration** for stack cleaning and defaults
 - **Serialization/deserialization** for network transfer and storage
+- **ErrorXResolver** for i18n, documentation URLs, and custom presentation logic
 - **Custom ErrorX class** examples:
   - `HTTPErrorX` - HTTP status code presets (400-511)
   - `DBErrorX` - Database error presets (connection, query, constraints)
@@ -60,7 +61,6 @@ throw new ErrorX({
   message: "User authentication failed",
   name: "AuthError",
   code: "AUTH_FAILED",
-  uiMessage: "Please check your credentials",
   httpStatus: 401,
   metadata: { userId: 123 },
 });
@@ -87,20 +87,19 @@ The base error class that extends the native `Error` with enhanced capabilities.
 
 #### Properties
 
-| Property     | Type                       | Description                                                    |
-| ------------ | -------------------------- | -------------------------------------------------------------- |
-| `message`    | `string`                   | Technical error message                                        |
-| `name`       | `string`                   | Error type/name                                                |
-| `code`       | `string`                   | Error identifier code (auto-generated from name if not set)    |
-| `uiMessage`  | `string \| undefined`      | User-friendly message for UI display                           |
-| `httpStatus` | `number \| undefined`      | HTTP status code associated with this error                    |
-| `metadata`   | `TMetadata \| undefined`   | Additional context (type-safe with generics)                   |
-| `timestamp`  | `number`                   | Unix epoch timestamp (ms) when error was created               |
-| `stack`      | `string \| undefined`      | Stack trace (inherited from Error)                             |
-| `chain`      | `readonly ErrorX[]`        | Full error sequence: `[this, parent, grandparent, ..., root]`  |
-| `root`       | `ErrorX \| undefined`      | Error that started the whole error chain                       |
-| `parent`     | `ErrorX \| undefined`      | Error that immediately precedes this error in the chain        |
-| `original`   | `ErrorXCause \| undefined` | Stores the original non-ErrorX error used to create this error |
+| Property     | Type                          | Description                                                    |
+| ------------ | ----------------------------- | -------------------------------------------------------------- |
+| `message`    | `string`                      | Technical error message                                        |
+| `name`       | `string`                      | Error type/name                                                |
+| `code`       | `string`                      | Error identifier code (auto-generated from name if not set)    |
+| `httpStatus` | `number \| undefined`         | HTTP status code associated with this error                    |
+| `metadata`   | `TMetadata \| undefined`      | Additional context (type-safe with generics)                   |
+| `timestamp`  | `number`                      | Unix epoch timestamp (ms) when error was created               |
+| `stack`      | `string \| undefined`         | Stack trace (inherited from Error)                             |
+| `chain`      | `readonly ErrorX[]`           | Full error sequence: `[this, parent, grandparent, ..., root]`  |
+| `root`       | `ErrorX \| undefined`         | Error that started the whole error chain                       |
+| `parent`     | `ErrorX \| undefined`         | Error that immediately precedes this error in the chain        |
+| `original`   | `ErrorXSnapshot \| undefined` | Stores the original non-ErrorX error used to create this error |
 
 #### Static Methods
 
@@ -143,7 +142,6 @@ new ErrorX({
   message: "User not found",
   name: "NotFoundError",
   code: "USER_NOT_FOUND",
-  uiMessage: "The requested user does not exist",
   httpStatus: 404,
   metadata: { userId: 123 },
 });
@@ -158,15 +156,78 @@ new ErrorX<UserMeta>({
 
 ### ErrorXOptions
 
-| Property   | Type                              | Default               | Description                               |
-| ---------- | --------------------------------- | --------------------- | ----------------------------------------- |
-| message    | `string`                          | `'An error occurred'` | Technical error message                   |
-| name       | `string`                          | `'Error'`             | Error type/name                           |
-| code       | `string \| number`                | Auto-generated        | Error identifier (UPPER_SNAKE_CASE)       |
-| uiMessage  | `string`                          | `undefined`           | User-friendly message                     |
-| httpStatus | `number`                          | `undefined`           | HTTP status code                          |
-| metadata   | `TMetadata`                       | `undefined`           | Additional context                        |
-| cause      | `ErrorXCause \| Error \| unknown` | `undefined`           | Error that caused this (builds the chain) |
+| Property   | Type               | Default               | Description                               |
+| ---------- | ------------------ | --------------------- | ----------------------------------------- |
+| message    | `string`           | `'An error occurred'` | Technical error message                   |
+| name       | `string`           | `'Error'`             | Error type/name                           |
+| code       | `string \| number` | Auto-generated        | Error identifier (UPPER_SNAKE_CASE)       |
+| httpStatus | `number`           | `undefined`           | HTTP status code                          |
+| metadata   | `TMetadata`        | `undefined`           | Additional context                        |
+| cause      | `unknown`          | `undefined`           | Error that caused this (builds the chain) |
+
+## Global Configuration
+
+Configure stack trace cleaning and other global settings.
+
+```typescript
+import { ErrorX } from "@bombillazo/error-x";
+
+// Enable stack cleaning with custom delimiter
+ErrorX.configure({
+  cleanStack: true,
+  cleanStackDelimiter: "my-app-entry",
+});
+
+// Custom patterns to remove from stack traces
+ErrorX.configure({
+  cleanStack: ["node_modules", "internal/"],
+});
+
+// Disable stack cleaning
+ErrorX.configure({ cleanStack: false });
+
+// Get current config
+const config = ErrorX.getConfig();
+
+// Reset to defaults
+ErrorX.resetConfig();
+```
+
+### Auto Code Generation
+
+Error codes are automatically generated from names in UPPER_SNAKE_CASE when not provided:
+
+```typescript
+new ErrorX({ name: "DatabaseError" });
+// → code: 'DATABASE_ERROR'
+
+new ErrorX({ name: "userAuthError" });
+// → code: 'USER_AUTH_ERROR'
+
+new ErrorX({ name: "API Timeout" });
+// → code: 'API_TIMEOUT'
+```
+
+### Message Formatting
+
+ErrorX does NOT auto-format messages. Messages are passed through as-is:
+
+```typescript
+new ErrorX({ message: "test error" });
+// → message: 'test error'
+
+new ErrorX({ message: "Test error." });
+// → message: 'Test error.'
+```
+
+Empty or whitespace-only messages default to `'An error occurred'`:
+
+```typescript
+new ErrorX({ message: "" });
+// → message: 'An error occurred'
+```
+
+Preset messages in specialized classes (HTTPErrorX, DBErrorX) are properly formatted with sentence casing and periods.
 
 ---
 
@@ -247,7 +308,7 @@ Serialize ErrorX instances for network transfer or storage.
 ```typescript
 // Serialize
 const json = error.toJSON();
-// { name, message, code, uiMessage, stack, metadata, timestamp, httpStatus, original, chain }
+// { name, message, code, stack, metadata, timestamp, httpStatus, original, chain }
 
 // Deserialize
 const restored = ErrorX.fromJSON(json);
@@ -288,7 +349,7 @@ try {
 if (ErrorX.isErrorX(error)) {
   console.log(
     "Error chain:",
-    error.chain.map((e) => e.name)
+    error.chain.map((e) => e.name),
   );
   console.log("Root cause:", error.root?.original);
 }
@@ -410,7 +471,6 @@ try {
 
 // With overrides
 ValidationErrorX.fromZodError(zodError, {
-  uiMessage: "Please check your input",
   httpStatus: 422,
 });
 
@@ -455,25 +515,29 @@ const paymentPresets = {
     code: "INSUFFICIENT_FUNDS",
     name: "PaymentError",
     message: "Insufficient funds.",
-    uiMessage: "Your payment method has insufficient funds.",
     httpStatus: 402,
   },
   CARD_DECLINED: {
     code: "CARD_DECLINED",
     name: "PaymentError",
     message: "Card declined.",
-    uiMessage: "Your card was declined. Please try another payment method.",
     httpStatus: 402,
   },
   EXPIRED_CARD: {
     code: "EXPIRED_CARD",
     name: "PaymentError",
     message: "Card expired.",
-    uiMessage: "Your card has expired. Please update your payment method.",
     httpStatus: 402,
   },
 } as const satisfies Record<string, ErrorXOptions>;
 
+// Optional: Define user-friendly messages separately
+export const paymentErrorUiMessages: Record<keyof typeof paymentPresets, string> = {
+  INSUFFICIENT_FUNDS: "Your payment method has insufficient funds.",
+  CARD_DECLINED: "Your card was declined. Please try another payment method.",
+  EXPIRED_CARD: "Your card has expired. Please update your payment method.",
+};
+
 // 3. Derive preset key type
 type PaymentPresetKey = keyof typeof paymentPresets | (string & {});
 
@@ -492,12 +556,12 @@ export class PaymentErrorX extends ErrorX<PaymentMetadata> {
   // Override create for proper typing
   static override create(
     presetKey?: PaymentPresetKey,
-    overrides?: Partial<ErrorXOptions<PaymentMetadata>>
+    overrides?: Partial<ErrorXOptions<PaymentMetadata>>,
   ): PaymentErrorX {
     return ErrorX.create.call(
       PaymentErrorX,
       presetKey,
-      overrides
+      overrides,
     ) as PaymentErrorX;
   }
 }
@@ -516,73 +580,155 @@ if (error instanceof PaymentErrorX) {
 
 ---
 
-## Other Usage
+## ErrorXResolver
 
-### Global Configuration
+The `ErrorXResolver` class resolves `ErrorX` instances to enhanced presentation objects with i18n support, documentation URLs, and custom properties.
 
-Configure stack trace cleaning and other global settings.
+### Basic Usage
 
 ```typescript
-import { ErrorX } from "@bombillazo/error-x";
+import { ErrorXResolver, HTTPErrorX } from "@bombillazo/error-x";
 
-// Enable stack cleaning with custom delimiter
-ErrorX.configure({
-  cleanStack: true,
-  cleanStackDelimiter: "my-app-entry",
+const resolver = new ErrorXResolver({
+  // Required: determine error type from error instance
+  onResolveType: (error) => {
+    if (error instanceof HTTPErrorX) return "http";
+    return "general";
+  },
+  // Per-type configuration
+  configs: {
+    http: { namespace: "errors.http" },
+    general: { namespace: "errors" },
+  },
 });
 
-// Custom patterns to remove from stack traces
-ErrorX.configure({
-  cleanStack: ["node_modules", "internal/"],
-});
+const error = HTTPErrorX.create(404);
+const result = resolver.resolve(error);
+// → { uiMessage: undefined, docsUrl: '', i18nKey: 'errors.http.NOT_FOUND', errorType: 'http', config: {...} }
+```
 
-// Disable stack cleaning
-ErrorX.configure({ cleanStack: false });
+### With i18n Integration
 
-// Get current config
-const config = ErrorX.getConfig();
+```typescript
+import i18next from "i18next";
 
-// Reset to defaults
-ErrorX.resetConfig();
+const resolver = new ErrorXResolver({
+  i18n: {
+    resolver: (key, params) => i18next.t(key, params),
+    keyTemplate: "{namespace}.{code}", // default
+  },
+  docs: {
+    baseUrl: "https://docs.example.com/errors",
+  },
+  onResolveType: (error) => (error.code.startsWith("HTTP_") ? "http" : "general"),
+  configs: {
+    http: { namespace: "errors.http", docsPath: "/http" },
+    general: { namespace: "errors.general" },
+  },
+});
+
+const result = resolver.resolve(error);
+// → { uiMessage: 'Not found', docsUrl: 'https://docs.example.com/errors/http#NOT_FOUND', ... }
 ```
 
-### Auto Code Generation
+### Custom Config Properties
 
-Error codes are automatically generated from names in UPPER_SNAKE_CASE when not provided:
+Extend the resolver with custom properties for your domain:
 
 ```typescript
-new ErrorX({ name: "DatabaseError" });
-// → code: 'DATABASE_ERROR'
+import { ErrorXResolver, type ErrorXResolverConfig } from "@bombillazo/error-x";
+
+// Define custom config with additional properties
+type MyConfig = ErrorXResolverConfig<{
+  severity: "error" | "warning" | "info";
+  retryable: boolean;
+}>;
+
+const resolver = new ErrorXResolver<MyConfig>({
+  onResolveType: (error) => "api",
+  defaults: {
+    namespace: "errors",
+    severity: "error",
+    retryable: false,
+  },
+  configs: {
+    api: {
+      namespace: "errors.api",
+      severity: "warning",
+      retryable: true,
+      // Per-code overrides
+      presets: {
+        NOT_FOUND: { severity: "info", retryable: false },
+      },
+    },
+  },
+});
+```
 
-new ErrorX({ name: "userAuthError" });
-// → code: 'USER_AUTH_ERROR'
+### Custom Result Type
 
-new ErrorX({ name: "API Timeout" });
-// → code: 'API_TIMEOUT'
+Transform the resolve output to match your API:
+
+```typescript
+type MyResult = { message: string; docs: string; canRetry: boolean };
+
+const resolver = new ErrorXResolver<MyConfig, MyResult>({
+  onResolveType: (error) => "api",
+  onResolve: (error, context) => ({
+    message: context.uiMessage ?? error.message,
+    docs: context.docsUrl,
+    canRetry: context.config.retryable,
+  }),
+  configs: { api: { namespace: "errors.api", retryable: true } },
+});
 ```
 
-### Message Formatting
+---
 
-ErrorX does NOT auto-format messages. Messages are passed through as-is:
+## UI Messages
+
+User-friendly messages are provided separately from error presets. This allows errors to remain technical while UI messages can be managed independently (e.g., for i18n).
+
+### Available Exports
 
 ```typescript
-new ErrorX({ message: "test error" });
-// → message: 'test error'
+import {
+  httpErrorUiMessages,
+  dbErrorUiMessages,
+  validationErrorUiMessage,
+} from "@bombillazo/error-x";
 
-new ErrorX({ message: "Test error." });
-// → message: 'Test error.'
-```
+// HTTP error messages keyed by status code
+httpErrorUiMessages[404]; // "The requested resource could not be found."
+httpErrorUiMessages[500]; // "An unexpected error occurred. Please try again later."
 
-Empty or whitespace-only messages default to `'An error occurred'`:
+// Database error messages keyed by preset name
+dbErrorUiMessages.CONNECTION_FAILED; // "Unable to connect to the database. Please try again later."
+dbErrorUiMessages.UNIQUE_VIOLATION; // "This record already exists."
 
-```typescript
-new ErrorX({ message: "" });
-// → message: 'An error occurred'
+// Validation error default message
+validationErrorUiMessage; // "The provided input is invalid. Please check your data."
 ```
 
-Preset messages in specialized classes (HTTPErrorX, DBErrorX) are properly formatted with sentence casing and periods.
+### Usage with ErrorXResolver
 
----
+```typescript
+import { ErrorXResolver, HTTPErrorX, httpErrorUiMessages } from "@bombillazo/error-x";
+
+const resolver = new ErrorXResolver({
+  onResolveType: () => "http",
+  configs: {
+    http: {
+      namespace: "errors.http",
+      presets: {
+        // Use provided UI messages as static fallbacks
+        NOT_FOUND: { uiMessage: httpErrorUiMessages[404] },
+        UNAUTHORIZED: { uiMessage: httpErrorUiMessages[401] },
+      },
+    },
+  },
+});
+```
 
 ## License