@bombillazo/error-x 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -207,6 +207,10 @@ type ErrorXOptions = {
     metadata?: ErrorMetadata;
     /** Actions to perform when this error occurs (default: undefined) */
     actions?: ErrorAction[];
+    /** HTTP status code (100-599) for HTTP-related errors (default: undefined) */
+    httpStatus?: number | undefined;
+    /** Error type for categorization */
+    type?: string | undefined;
 };
 /**
  * JSON-serializable representation of an ErrorX instance.
@@ -255,6 +259,10 @@ type SerializableError = {
     actions?: ErrorAction[];
     /** Serialized cause error (for error chaining) */
     cause?: SerializableError;
+    /** HTTP status code for HTTP-related errors */
+    httpStatus?: number;
+    /** Error type for categorization */
+    type?: string;
 };
 
 /**
@@ -288,6 +296,10 @@ declare class ErrorX extends Error {
     readonly timestamp: Date;
     /** Error actions for UI behavior and handling */
     readonly actions: ErrorAction[] | undefined;
+    /** HTTP status code (100-599) for HTTP-related errors */
+    readonly httpStatus: number | undefined;
+    /** Error type for categorization */
+    readonly type: string | undefined;
     /**
      * Creates a new ErrorX instance with enhanced error handling capabilities.
      *
@@ -331,6 +343,20 @@ declare class ErrorX extends Error {
      * @returns Default error name 'Error'
      */
     private static getDefaultName;
+    /**
+     * Validates HTTP status code to ensure it's within valid range (100-599)
+     *
+     * @param status - Status code to validate
+     * @returns Valid status code or undefined if invalid/not provided
+     */
+    private static validateHttpStatus;
+    /**
+     * 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.
@@ -572,4 +598,452 @@ declare class ErrorX extends Error {
     static fromJSON(serialized: SerializableError): ErrorX;
 }
 
-export { type CustomAction, type ErrorAction, type ErrorMetadata, ErrorX, type ErrorXOptions, type HandlingTarget, HandlingTargets, type LogoutAction, type NotifyAction, type RedirectAction, type SerializableError };
+/**
+ * Preset configurations for common errors organized by category.
+ *
+ * ## Features
+ * - **Pre-configured error templates** for common HTTP status codes (400-511)
+ * - **Type-safe** with TypeScript support
+ * - **Fully customizable** via destructuring and override pattern
+ * - **User-friendly messages** included for all presets
+ * - **Categorized by type** - all HTTP presets include `type: 'http'`
+ *
+ * ## Available Categories
+ * - **HTTP**: Common HTTP status codes (4xx client errors, 5xx server errors)
+ *
+ * ## Usage Patterns
+ *
+ * ### 1. Direct Usage
+ * Use a preset as-is without any modifications:
+ * ```typescript
+ * import { ErrorX, PRESETS } from '@bombillazo/error-x'
+ *
+ * throw new ErrorX(PRESETS.HTTP.NOT_FOUND)
+ * // Result: 404 error with default message and UI message
+ * ```
+ *
+ * ### 2. Override Specific Fields
+ * Customize the error while keeping other preset values:
+ * ```typescript
+ * throw new ErrorX({
+ *   ...PRESETS.HTTP.NOT_FOUND,
+ *   message: 'User not found',
+ *   metadata: { userId: 123 }
+ * })
+ * // Result: 404 error with custom message but keeps httpStatus, code, name, uiMessage, type
+ * ```
+ *
+ * ### 3. Add Metadata and Actions
+ * Enhance presets with additional context and behaviors:
+ * ```typescript
+ * throw new ErrorX({
+ *   ...PRESETS.HTTP.UNAUTHORIZED,
+ *   metadata: { attemptedAction: 'viewProfile', userId: 456 },
+ *   actions: [
+ *     { action: 'logout', payload: { clearStorage: true } },
+ *     { action: 'redirect', payload: { redirectURL: '/login' } }
+ *   ]
+ * })
+ * ```
+ *
+ * ### 4. Add Error Cause
+ * Chain errors by adding a cause:
+ * ```typescript
+ * try {
+ *   // some operation
+ * } catch (originalError) {
+ *   throw new ErrorX({
+ *     ...PRESETS.HTTP.INTERNAL_SERVER_ERROR,
+ *     cause: originalError,
+ *     metadata: { operation: 'database-query' }
+ *   })
+ * }
+ * ```
+ *
+ * ## Common HTTP Presets
+ *
+ * ### 4xx Client Errors
+ * - `BAD_REQUEST` (400) - Invalid request data
+ * - `UNAUTHORIZED` (401) - Authentication required
+ * - `FORBIDDEN` (403) - Insufficient permissions
+ * - `NOT_FOUND` (404) - Resource not found
+ * - `METHOD_NOT_ALLOWED` (405) - HTTP method not allowed
+ * - `CONFLICT` (409) - Resource conflict
+ * - `UNPROCESSABLE_ENTITY` (422) - Validation failed
+ * - `TOO_MANY_REQUESTS` (429) - Rate limit exceeded
+ *
+ * ### 5xx Server Errors
+ * - `INTERNAL_SERVER_ERROR` (500) - Unexpected server error
+ * - `NOT_IMPLEMENTED` (501) - Feature not implemented
+ * - `BAD_GATEWAY` (502) - Upstream server error
+ * - `SERVICE_UNAVAILABLE` (503) - Service temporarily down
+ * - `GATEWAY_TIMEOUT` (504) - Upstream timeout
+ *
+ * @example
+ * ```typescript
+ * import { ErrorX, PRESETS } from '@bombillazo/error-x'
+ *
+ * // API endpoint example
+ * app.get('/users/:id', async (req, res) => {
+ *   const user = await db.users.findById(req.params.id)
+ *
+ *   if (!user) {
+ *     throw new ErrorX({
+ *       ...PRESETS.HTTP.NOT_FOUND,
+ *       message: 'User not found',
+ *       metadata: { userId: req.params.id }
+ *     })
+ *   }
+ *
+ *   res.json(user)
+ * })
+ *
+ * // Authentication middleware example
+ * const requireAuth = (req, res, next) => {
+ *   if (!req.user) {
+ *     throw new ErrorX({
+ *       ...PRESETS.HTTP.UNAUTHORIZED,
+ *       actions: [
+ *         { action: 'redirect', payload: { redirectURL: '/login' } }
+ *       ]
+ *     })
+ *   }
+ *   next()
+ * }
+ *
+ * // Rate limiting example
+ * if (isRateLimited(req.ip)) {
+ *   throw new ErrorX({
+ *     ...PRESETS.HTTP.TOO_MANY_REQUESTS,
+ *     metadata: {
+ *       ip: req.ip,
+ *       retryAfter: 60
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * @public
+ */
+declare const PRESETS: {
+    /**
+     * HTTP error presets for common HTTP status codes.
+     * Includes both 4xx client errors and 5xx server errors.
+     */
+    readonly HTTP: {
+        readonly BAD_REQUEST: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly UNAUTHORIZED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly PAYMENT_REQUIRED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly FORBIDDEN: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly NOT_FOUND: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly METHOD_NOT_ALLOWED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly NOT_ACCEPTABLE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly PROXY_AUTHENTICATION_REQUIRED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly REQUEST_TIMEOUT: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly CONFLICT: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly GONE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly LENGTH_REQUIRED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly PRECONDITION_FAILED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly PAYLOAD_TOO_LARGE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly URI_TOO_LONG: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly UNSUPPORTED_MEDIA_TYPE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly RANGE_NOT_SATISFIABLE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly EXPECTATION_FAILED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly IM_A_TEAPOT: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly UNPROCESSABLE_ENTITY: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly LOCKED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly FAILED_DEPENDENCY: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly TOO_EARLY: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly UPGRADE_REQUIRED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly PRECONDITION_REQUIRED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly TOO_MANY_REQUESTS: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly REQUEST_HEADER_FIELDS_TOO_LARGE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly UNAVAILABLE_FOR_LEGAL_REASONS: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly INTERNAL_SERVER_ERROR: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly NOT_IMPLEMENTED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly BAD_GATEWAY: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly SERVICE_UNAVAILABLE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly GATEWAY_TIMEOUT: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly HTTP_VERSION_NOT_SUPPORTED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly VARIANT_ALSO_NEGOTIATES: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly INSUFFICIENT_STORAGE: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly LOOP_DETECTED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly NOT_EXTENDED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+        readonly NETWORK_AUTHENTICATION_REQUIRED: {
+            httpStatus: number;
+            code: string;
+            name: string;
+            message: string;
+            uiMessage: string;
+            type: string;
+        };
+    };
+};
+
+export { type CustomAction, type ErrorAction, type ErrorMetadata, ErrorX, type ErrorXOptions, type HandlingTarget, HandlingTargets, type LogoutAction, type NotifyAction, PRESETS, type RedirectAction, type SerializableError };