@bombillazo/error-x 0.2.1 → 0.3.0

package/dist/index.cjs

@@ -652,132 +652,244 @@ ${this.stack}`;
     }
     return error;
   }
-};
-
-// src/presets.ts
-var 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
    */
-  HTTP: {
+  static HTTP = {
     // 4xx Client Errors
     BAD_REQUEST: {
       httpStatus: 400,
       code: "BAD_REQUEST",
-      name: "BadRequestError",
-      message: "Bad request",
+      name: "Bad Request Error",
+      message: "bad request",
       uiMessage: "The request could not be processed. Please check your input and try again.",
       type: "http"
     },
     UNAUTHORIZED: {
       httpStatus: 401,
       code: "UNAUTHORIZED",
-      name: "UnauthorizedError",
-      message: "Unauthorized",
+      name: "Unauthorized Error",
+      message: "unauthorized",
       uiMessage: "Authentication required. Please log in to continue.",
       type: "http"
     },
     PAYMENT_REQUIRED: {
       httpStatus: 402,
       code: "PAYMENT_REQUIRED",
-      name: "PaymentRequiredError",
-      message: "Payment required",
+      name: "Payment Required Error",
+      message: "payment required",
       uiMessage: "Payment is required to access this resource.",
       type: "http"
     },
     FORBIDDEN: {
       httpStatus: 403,
       code: "FORBIDDEN",
-      name: "ForbiddenError",
-      message: "Forbidden",
+      name: "Forbidden Error",
+      message: "forbidden",
       uiMessage: "You do not have permission to access this resource.",
       type: "http"
     },
     NOT_FOUND: {
       httpStatus: 404,
       code: "NOT_FOUND",
-      name: "NotFoundError",
-      message: "Not found",
+      name: "Not Found Error",
+      message: "not found",
       uiMessage: "The requested resource could not be found.",
       type: "http"
     },
     METHOD_NOT_ALLOWED: {
       httpStatus: 405,
       code: "METHOD_NOT_ALLOWED",
-      name: "MethodNotAllowedError",
-      message: "Method not allowed",
+      name: "Method Not Allowed Error",
+      message: "method not allowed",
       uiMessage: "This action is not allowed for the requested resource.",
       type: "http"
     },
     NOT_ACCEPTABLE: {
       httpStatus: 406,
       code: "NOT_ACCEPTABLE",
-      name: "NotAcceptableError",
-      message: "Not acceptable",
+      name: "Not Acceptable Error",
+      message: "not acceptable",
       uiMessage: "The requested format is not supported.",
       type: "http"
     },
     PROXY_AUTHENTICATION_REQUIRED: {
       httpStatus: 407,
       code: "PROXY_AUTHENTICATION_REQUIRED",
-      name: "ProxyAuthenticationRequiredError",
-      message: "Proxy authentication required",
+      name: "Proxy Authentication Required Error",
+      message: "proxy authentication required",
       uiMessage: "Proxy authentication is required to access this resource.",
       type: "http"
     },
     REQUEST_TIMEOUT: {
       httpStatus: 408,
       code: "REQUEST_TIMEOUT",
-      name: "RequestTimeoutError",
-      message: "Request timeout",
+      name: "Request Timeout Error",
+      message: "request timeout",
       uiMessage: "The request took too long to complete. Please try again.",
       type: "http"
     },
     CONFLICT: {
       httpStatus: 409,
       code: "CONFLICT",
-      name: "ConflictError",
-      message: "Conflict",
+      name: "Conflict Error",
+      message: "conflict",
       uiMessage: "The request conflicts with the current state. Please refresh and try again.",
       type: "http"
     },
     GONE: {
       httpStatus: 410,
       code: "GONE",
-      name: "GoneError",
-      message: "Gone",
+      name: "Gone Error",
+      message: "gone",
       uiMessage: "This resource is no longer available.",
       type: "http"
     },
     LENGTH_REQUIRED: {
       httpStatus: 411,
       code: "LENGTH_REQUIRED",
-      name: "LengthRequiredError",
-      message: "Length required",
+      name: "Length Required Error",
+      message: "length required",
       uiMessage: "The request is missing required length information.",
       type: "http"
     },
     PRECONDITION_FAILED: {
       httpStatus: 412,
       code: "PRECONDITION_FAILED",
-      name: "PreconditionFailedError",
-      message: "Precondition failed",
+      name: "Precondition Failed Error",
+      message: "precondition failed",
       uiMessage: "A required condition was not met. Please try again.",
       type: "http"
     },
     PAYLOAD_TOO_LARGE: {
       httpStatus: 413,
       code: "PAYLOAD_TOO_LARGE",
-      name: "PayloadTooLargeError",
-      message: "Payload too large",
+      name: "Payload Too Large Error",
+      message: "payload too large",
       uiMessage: "The request is too large. Please reduce the size and try again.",
       type: "http"
     },
     URI_TOO_LONG: {
       httpStatus: 414,
       code: "URI_TOO_LONG",
-      name: "URITooLongError",
+      name: "URI Too Long Error",
       message: "URI too long",
       uiMessage: "The request URL is too long.",
       type: "http"
@@ -785,104 +897,104 @@ var PRESETS = {
     UNSUPPORTED_MEDIA_TYPE: {
       httpStatus: 415,
       code: "UNSUPPORTED_MEDIA_TYPE",
-      name: "UnsupportedMediaTypeError",
-      message: "Unsupported media type",
+      name: "Unsupported Media Type Error",
+      message: "unsupported media type",
       uiMessage: "The file type is not supported.",
       type: "http"
     },
     RANGE_NOT_SATISFIABLE: {
       httpStatus: 416,
       code: "RANGE_NOT_SATISFIABLE",
-      name: "RangeNotSatisfiableError",
-      message: "Range not satisfiable",
+      name: "Range Not Satisfiable Error",
+      message: "range not satisfiable",
       uiMessage: "The requested range cannot be satisfied.",
       type: "http"
     },
     EXPECTATION_FAILED: {
       httpStatus: 417,
       code: "EXPECTATION_FAILED",
-      name: "ExpectationFailedError",
-      message: "Expectation failed",
+      name: "Expectation Failed Error",
+      message: "expectation failed",
       uiMessage: "The server cannot meet the requirements of the request.",
       type: "http"
     },
     IM_A_TEAPOT: {
       httpStatus: 418,
       code: "IM_A_TEAPOT",
-      name: "ImATeapotError",
-      message: "I'm a teapot",
+      name: "Im A Teapot Error",
+      message: "i'm a teapot",
       uiMessage: "I'm a teapot and cannot brew coffee.",
       type: "http"
     },
     UNPROCESSABLE_ENTITY: {
       httpStatus: 422,
       code: "UNPROCESSABLE_ENTITY",
-      name: "UnprocessableEntityError",
-      message: "Unprocessable entity",
+      name: "Unprocessable Entity Error",
+      message: "unprocessable entity",
       uiMessage: "The request contains invalid data. Please check your input.",
       type: "http"
     },
     LOCKED: {
       httpStatus: 423,
       code: "LOCKED",
-      name: "LockedError",
-      message: "Locked",
+      name: "Locked Error",
+      message: "locked",
       uiMessage: "This resource is locked and cannot be modified.",
       type: "http"
     },
     FAILED_DEPENDENCY: {
       httpStatus: 424,
       code: "FAILED_DEPENDENCY",
-      name: "FailedDependencyError",
-      message: "Failed dependency",
+      name: "Failed Dependency Error",
+      message: "failed dependency",
       uiMessage: "The request failed due to a dependency error.",
       type: "http"
     },
     TOO_EARLY: {
       httpStatus: 425,
       code: "TOO_EARLY",
-      name: "TooEarlyError",
-      message: "Too early",
+      name: "Too Early Error",
+      message: "too early",
       uiMessage: "The request was sent too early. Please try again later.",
       type: "http"
     },
     UPGRADE_REQUIRED: {
       httpStatus: 426,
       code: "UPGRADE_REQUIRED",
-      name: "UpgradeRequiredError",
-      message: "Upgrade required",
+      name: "Upgrade Required Error",
+      message: "upgrade required",
       uiMessage: "Please upgrade to continue using this service.",
       type: "http"
     },
     PRECONDITION_REQUIRED: {
       httpStatus: 428,
       code: "PRECONDITION_REQUIRED",
-      name: "PreconditionRequiredError",
-      message: "Precondition required",
+      name: "Precondition Required Error",
+      message: "precondition required",
       uiMessage: "Required conditions are missing from the request.",
       type: "http"
     },
     TOO_MANY_REQUESTS: {
       httpStatus: 429,
       code: "TOO_MANY_REQUESTS",
-      name: "TooManyRequestsError",
-      message: "Too many requests",
+      name: "Too Many Requests Error",
+      message: "too many requests",
       uiMessage: "You have made too many requests. Please wait and try again.",
       type: "http"
     },
     REQUEST_HEADER_FIELDS_TOO_LARGE: {
       httpStatus: 431,
       code: "REQUEST_HEADER_FIELDS_TOO_LARGE",
-      name: "RequestHeaderFieldsTooLargeError",
-      message: "Request header fields too large",
+      name: "Request Header Fields Too Large Error",
+      message: "request header fields too large",
       uiMessage: "The request headers are too large.",
       type: "http"
     },
     UNAVAILABLE_FOR_LEGAL_REASONS: {
       httpStatus: 451,
       code: "UNAVAILABLE_FOR_LEGAL_REASONS",
-      name: "UnavailableForLegalReasonsError",
-      message: "Unavailable for legal reasons",
+      name: "Unavailable For Legal Reasons Error",
+      message: "unavailable for legal reasons",
       uiMessage: "This content is unavailable for legal reasons.",
       type: "http"
     },
@@ -890,47 +1002,47 @@ var PRESETS = {
     INTERNAL_SERVER_ERROR: {
       httpStatus: 500,
       code: "INTERNAL_SERVER_ERROR",
-      name: "InternalServerError",
-      message: "Internal server error",
+      name: "Internal Server Error",
+      message: "internal server error",
       uiMessage: "An unexpected error occurred. Please try again later.",
       type: "http"
     },
     NOT_IMPLEMENTED: {
       httpStatus: 501,
       code: "NOT_IMPLEMENTED",
-      name: "NotImplementedError",
-      message: "Not implemented",
+      name: "Not Implemented Error",
+      message: "not implemented",
       uiMessage: "This feature is not yet available.",
       type: "http"
     },
     BAD_GATEWAY: {
       httpStatus: 502,
       code: "BAD_GATEWAY",
-      name: "BadGatewayError",
-      message: "Bad gateway",
+      name: "Bad Gateway Error",
+      message: "bad gateway",
       uiMessage: "Unable to connect to the server. Please try again later.",
       type: "http"
     },
     SERVICE_UNAVAILABLE: {
       httpStatus: 503,
       code: "SERVICE_UNAVAILABLE",
-      name: "ServiceUnavailableError",
-      message: "Service unavailable",
+      name: "Service Unavailable Error",
+      message: "service unavailable",
       uiMessage: "The service is temporarily unavailable. Please try again later.",
       type: "http"
     },
     GATEWAY_TIMEOUT: {
       httpStatus: 504,
       code: "GATEWAY_TIMEOUT",
-      name: "GatewayTimeoutError",
-      message: "Gateway timeout",
+      name: "Gateway Timeout Error",
+      message: "gateway timeout",
       uiMessage: "The server took too long to respond. Please try again.",
       type: "http"
     },
     HTTP_VERSION_NOT_SUPPORTED: {
       httpStatus: 505,
       code: "HTTP_VERSION_NOT_SUPPORTED",
-      name: "HTTPVersionNotSupportedError",
+      name: "HTTP Version Not Supported Error",
       message: "HTTP version not supported",
       uiMessage: "Your browser version is not supported.",
       type: "http"
@@ -938,48 +1050,47 @@ var PRESETS = {
     VARIANT_ALSO_NEGOTIATES: {
       httpStatus: 506,
       code: "VARIANT_ALSO_NEGOTIATES",
-      name: "VariantAlsoNegotiatesError",
-      message: "Variant also negotiates",
+      name: "Variant Also Negotiates Error",
+      message: "variant also negotiates",
       uiMessage: "The server has an internal configuration error.",
       type: "http"
     },
     INSUFFICIENT_STORAGE: {
       httpStatus: 507,
       code: "INSUFFICIENT_STORAGE",
-      name: "InsufficientStorageError",
-      message: "Insufficient storage",
+      name: "Insufficient Storage Error",
+      message: "insufficient storage",
       uiMessage: "The server has insufficient storage to complete the request.",
       type: "http"
     },
     LOOP_DETECTED: {
       httpStatus: 508,
       code: "LOOP_DETECTED",
-      name: "LoopDetectedError",
-      message: "Loop detected",
+      name: "Loop Detected Error",
+      message: "loop detected",
       uiMessage: "The server detected an infinite loop.",
       type: "http"
     },
     NOT_EXTENDED: {
       httpStatus: 510,
       code: "NOT_EXTENDED",
-      name: "NotExtendedError",
-      message: "Not extended",
+      name: "Not Extended Error",
+      message: "not extended",
       uiMessage: "Additional extensions are required.",
       type: "http"
     },
     NETWORK_AUTHENTICATION_REQUIRED: {
       httpStatus: 511,
       code: "NETWORK_AUTHENTICATION_REQUIRED",
-      name: "NetworkAuthenticationRequiredError",
-      message: "Network authentication required",
+      name: "Network Authentication Required Error",
+      message: "network authentication required",
       uiMessage: "Network authentication is required to access this resource.",
       type: "http"
     }
-  }
+  };
 };
 
 exports.ErrorX = ErrorX;
 exports.HandlingTargets = HandlingTargets;
-exports.PRESETS = PRESETS;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map