@bombillazo/error-x 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -596,41 +596,127 @@ declare class ErrorX extends Error {
      * ```
      */
     static fromJSON(serialized: SerializableError): ErrorX;
-}
-
-/**
- * Preset configurations for common errors organized by category.
- * Each preset includes httpStatus (for HTTP errors), code, name, message, and uiMessage.
- *
- * @example
- * ```typescript
- * import { ErrorX, ErrorPresets } from '@bombillazo/error-x'
- *
- * // Use preset directly
- * const error = new ErrorX(ErrorPresets.HTTP.NOT_FOUND)
- *
- * // Override preset values
- * const error = new ErrorX({
- *   ...ErrorPresets.HTTP.NOT_FOUND,
- *   message: 'User not found',
- *   metadata: { userId: 123 }
- * })
- *
- * // Use with additional options
- * const error = new ErrorX({
- *   ...ErrorPresets.HTTP.UNAUTHORIZED,
- *   actions: [{ action: 'redirect', payload: { redirectURL: '/login' } }]
- * })
- * ```
- *
- * @public
- */
-declare const PRESETS: {
     /**
      * HTTP error presets for common HTTP status codes.
-     * Includes both 4xx client errors and 5xx server errors.
+     *
+     * ## Features
+     * - **Pre-configured error templates** for common HTTP status codes (400-511)
+     * - **Type-safe** with TypeScript support
+     * - **Fully customizable** via destructuring and override pattern
+     * - **User-friendly messages** included for all presets
+     * - **Categorized by type** - all HTTP presets include `type: 'http'`
+     *
+     * ## Usage Patterns
+     *
+     * ### 1. Direct Usage
+     * Use a preset as-is without any modifications:
+     * ```typescript
+     * throw new ErrorX(ErrorX.HTTP.NOT_FOUND)
+     * // Result: 404 error with default message and UI message
+     * ```
+     *
+     * ### 2. Override Specific Fields
+     * Customize the error while keeping other preset values:
+     * ```typescript
+     * throw new ErrorX({
+     *   ...ErrorX.HTTP.NOT_FOUND,
+     *   message: 'User not found',
+     *   metadata: { userId: 123 }
+     * })
+     * // Result: 404 error with custom message but keeps httpStatus, code, name, uiMessage, type
+     * ```
+     *
+     * ### 3. Add Metadata and Actions
+     * Enhance presets with additional context and behaviors:
+     * ```typescript
+     * throw new ErrorX({
+     *   ...ErrorX.HTTP.UNAUTHORIZED,
+     *   metadata: { attemptedAction: 'viewProfile', userId: 456 },
+     *   actions: [
+     *     { action: 'logout', payload: { clearStorage: true } },
+     *     { action: 'redirect', payload: { redirectURL: '/login' } }
+     *   ]
+     * })
+     * ```
+     *
+     * ### 4. Add Error Cause
+     * Chain errors by adding a cause:
+     * ```typescript
+     * try {
+     *   // some operation
+     * } catch (originalError) {
+     *   throw new ErrorX({
+     *     ...ErrorX.HTTP.INTERNAL_SERVER_ERROR,
+     *     cause: originalError,
+     *     metadata: { operation: 'database-query' }
+     *   })
+     * }
+     * ```
+     *
+     * ## Common HTTP Presets
+     *
+     * ### 4xx Client Errors
+     * - `BAD_REQUEST` (400) - Invalid request data
+     * - `UNAUTHORIZED` (401) - Authentication required
+     * - `FORBIDDEN` (403) - Insufficient permissions
+     * - `NOT_FOUND` (404) - Resource not found
+     * - `METHOD_NOT_ALLOWED` (405) - HTTP method not allowed
+     * - `CONFLICT` (409) - Resource conflict
+     * - `UNPROCESSABLE_ENTITY` (422) - Validation failed
+     * - `TOO_MANY_REQUESTS` (429) - Rate limit exceeded
+     *
+     * ### 5xx Server Errors
+     * - `INTERNAL_SERVER_ERROR` (500) - Unexpected server error
+     * - `NOT_IMPLEMENTED` (501) - Feature not implemented
+     * - `BAD_GATEWAY` (502) - Upstream server error
+     * - `SERVICE_UNAVAILABLE` (503) - Service temporarily down
+     * - `GATEWAY_TIMEOUT` (504) - Upstream timeout
+     *
+     * @example
+     * ```typescript
+     * // API endpoint example
+     * app.get('/users/:id', async (req, res) => {
+     *   const user = await db.users.findById(req.params.id)
+     *
+     *   if (!user) {
+     *     throw new ErrorX({
+     *       ...ErrorX.HTTP.NOT_FOUND,
+     *       message: 'User not found',
+     *       metadata: { userId: req.params.id }
+     *     })
+     *   }
+     *
+     *   res.json(user)
+     * })
+     *
+     * // Authentication middleware example
+     * const requireAuth = (req, res, next) => {
+     *   if (!req.user) {
+     *     throw new ErrorX({
+     *       ...ErrorX.HTTP.UNAUTHORIZED,
+     *       actions: [
+     *         { action: 'redirect', payload: { redirectURL: '/login' } }
+     *       ]
+     *     })
+     *   }
+     *   next()
+     * }
+     *
+     * // Rate limiting example
+     * if (isRateLimited(req.ip)) {
+     *   throw new ErrorX({
+     *     ...ErrorX.HTTP.TOO_MANY_REQUESTS,
+     *     metadata: {
+     *       ip: req.ip,
+     *       retryAfter: 60
+     *     }
+     *   })
+     * }
+     * ```
+     *
+     * @public
      */
-    readonly HTTP: {
+    static readonly HTTP: {
         readonly BAD_REQUEST: {
             httpStatus: number;
             code: string;
@@ -944,6 +1030,6 @@ declare const PRESETS: {
             type: string;
         };
     };
-};
+}
 
-export { type CustomAction, type ErrorAction, type ErrorMetadata, ErrorX, type ErrorXOptions, type HandlingTarget, HandlingTargets, type LogoutAction, type NotifyAction, PRESETS, type RedirectAction, type SerializableError };
+export { type CustomAction, type ErrorAction, type ErrorMetadata, ErrorX, type ErrorXOptions, type HandlingTarget, HandlingTargets, type LogoutAction, type NotifyAction, type RedirectAction, type SerializableError };