@bombillazo/error-x 0.1.1 → 0.2.1

package/dist/index.d.cts

@@ -167,6 +167,29 @@ type ErrorAction = NotifyAction | LogoutAction | RedirectAction | CustomAction;
  * Configuration options for creating an ErrorX instance.
  * All properties are optional with sensible defaults.
  *
+ * @remarks
+ * **Note on design:** ErrorXOptions is a `type` instead of a `class` to provide maximum flexibility.
+ * This allows you to pass plain objects without instantiation:
+ *
+ * ```typescript
+ * // ✅ Works - plain object
+ * new ErrorX({ message: 'Error', code: 'ERR' })
+ *
+ * // ✅ Works - object literal
+ * const opts = { message: 'Error' }
+ * new ErrorX(opts)
+ * ```
+ *
+ * If ErrorXOptions were a class, you would need to instantiate it:
+ *
+ * ```typescript
+ * // ❌ Would be required with class
+ * new ErrorX(new ErrorXOptions({ message: 'Error' }))
+ * ```
+ *
+ * The current `type` approach provides better ergonomics while still maintaining type safety.
+ * The `isErrorXOptions()` validation method ensures only valid option objects are accepted.
+ *
  * @public
  */
 type ErrorXOptions = {
@@ -184,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.
@@ -232,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;
 };
 
 /**
@@ -265,52 +296,75 @@ 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.
      *
-     * @param options - Configuration options for the error (optional)
-     * @param options.message - Technical error message (defaults to 'An error occurred')
-     * @param options.name - Error type/name (defaults to 'Error')
-     * @param options.code - Error identifier code (auto-generated from name if not provided)
-     * @param options.uiMessage - User-friendly message (defaults to undefined)
-     * @param options.cause - Original error that caused this error
-     * @param options.metadata - Additional context data (defaults to undefined)
-     * @param options.actions - Error actions for UI behavior and handling (defaults to undefined)
+     * @param messageOrOptions - Error message string, ErrorXOptions object, or any value to convert to ErrorX
+     * @param additionalOptions - Additional options when first parameter is a string (optional)
      *
      * @example
      * ```typescript
-     * // Create with full options
-     * const error = new ErrorX({
-     *   message: 'Database query failed',
+     * // Create with string message only
+     * const error1 = new ErrorX('Database query failed')
+     *
+     * // Create with string message and additional options
+     * const error2 = new ErrorX('Database query failed', {
      *   name: 'DatabaseError',
      *   code: 'DB_QUERY_FAILED',
      *   uiMessage: 'Unable to load data. Please try again.',
-     *   metadata: { query: 'SELECT * FROM users', timeout: 5000 },
+     *   metadata: { query: 'SELECT * FROM users', timeout: 5000 }
+     * })
+     *
+     * // Create with options object (backward compatible)
+     * const error3 = new ErrorX({
+     *   message: 'Database query failed',
+     *   name: 'DatabaseError',
+     *   code: 'DB_QUERY_FAILED',
      *   actions: [
-     *     {
-     *       action: 'notify',
-     *       payload: { targets: [HandlingTargets.TOAST] }
-     *     },
-     *     {
-     *       action: 'redirect',
-     *       payload: { redirectURL: '/dashboard', delay: 1000 }
-     *     }
+     *     { action: 'notify', payload: { targets: [HandlingTargets.TOAST] } }
      *   ]
      * })
      *
-     * // Create with minimal options
-     * const simpleError = new ErrorX({ message: 'Something failed' })
+     * // Create with unknown input (smart conversion)
+     * const apiError = { message: 'User not found', code: 404 }
+     * const error4 = new ErrorX(apiError)
      *
      * // Create with no options (uses defaults)
-     * const defaultError = new ErrorX()
+     * const error5 = new ErrorX()
      * ```
      */
-    constructor(options?: ErrorXOptions);
+    constructor(messageOrOptions?: string | ErrorXOptions | unknown, additionalOptions?: Partial<ErrorXOptions>);
     /**
      * Returns the default error name.
      * @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.
+     *
+     * @param value - Value to check
+     * @returns True if value is a valid ErrorXOptions object
+     */
+    static isErrorXOptions(value: unknown): value is ErrorXOptions;
     /**
      * Generates a default error code from the error name.
      * Converts camelCase/PascalCase names to UPPER_SNAKE_CASE format.
@@ -414,6 +468,16 @@ declare class ErrorX extends Error {
      * ```
      */
     static isErrorX(value: unknown): value is ErrorX;
+    /**
+     * Converts unknown input into ErrorXOptions with intelligent property extraction.
+     * Handles strings, regular Error objects, API response objects, and unknown values.
+     * This is a private helper method used by both the constructor and toErrorX.
+     *
+     * @param error - Value to convert to ErrorXOptions
+     * @returns ErrorXOptions object with extracted properties
+     * @internal
+     */
+    private static convertUnknownToOptions;
     /**
      * Converts unknown input into an ErrorX instance with intelligent property extraction.
      * Handles strings, regular Error objects, API response objects, and unknown values.
@@ -534,4 +598,352 @@ 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.
+ * 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.
+     */
+    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 };