@bombillazo/error-x 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,537 @@
+/**
+ * Metadata object containing additional context information for an error.
+ * Can store any key-value pairs to provide extra debugging or business context.
+ *
+ * @example
+ * ```typescript
+ * const metadata: ErrorMetadata = {
+ *   userId: 123,
+ *   operation: 'fetchUser',
+ *   retryCount: 3
+ * }
+ * ```
+ *
+ * @public
+ */
+type ErrorMetadata = Record<string, any>;
+/**
+ * Predefined display targets for error notifications and UI feedback.
+ * These enum values provide consistent, type-safe options for where errors should be displayed.
+ *
+ * @public
+ */
+declare enum HandlingTargets {
+    MODAL = "modal",
+    TOAST = "toast",
+    INLINE = "inline",
+    BANNER = "banner",
+    CONSOLE = "console",
+    LOGGER = "logger",
+    NOTIFICATION = "notification"
+}
+/**
+ * Display target type that allows both predefined enum values and custom strings.
+ * This enables flexibility for custom UI components while providing standard options.
+ *
+ * @example
+ * ```typescript
+ * // Using predefined enum values
+ * targets: [HandlingTargets.MODAL, HandlingTargets.TOAST]
+ *
+ * // Using custom strings
+ * targets: ['custom-sidebar', 'my-notification-center']
+ *
+ * // Mixing both
+ * targets: [HandlingTargets.MODAL, 'custom-popup', HandlingTargets.CONSOLE]
+ * ```
+ *
+ * @public
+ */
+type HandlingTarget = HandlingTargets | string;
+/**
+ * Action to display notifications in specified UI targets.
+ * Used to notify applications to handle error messages through the indicated display mechanisms.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   action: 'notify',
+ *   payload: {
+ *     targets: [HandlingTargets.TOAST, 'custom-sidebar'],
+ *     title: 'Error occurred',
+ *     duration: 5000
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+type NotifyAction = {
+    action: 'notify';
+    payload: {
+        targets: HandlingTarget[];
+        [key: string]: any;
+    };
+};
+/**
+ * Action to log out the current user when an error occurs.
+ * Useful for authentication errors or session expiration.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   action: 'logout',
+ *   payload: {
+ *     clearStorage: true,
+ *     redirectURL: '/login'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+type LogoutAction = {
+    action: 'logout';
+    payload?: {
+        [key: string]: any;
+    };
+};
+/**
+ * Action to redirect the user to a different URL when an error occurs.
+ * Commonly used for navigation after authentication errors or access denied scenarios.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   action: 'redirect',
+ *   payload: {
+ *     redirectURL: '/login',
+ *     delay: 2000,
+ *     replace: true,
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+type RedirectAction = {
+    action: 'redirect';
+    payload: {
+        redirectURL: string;
+        [key: string]: any;
+    };
+};
+/**
+ * Custom action type for application-specific actions.
+ * This type is essential for proper TypeScript discrimination in the ErrorAction union.
+ * Without this, TypeScript cannot properly distinguish between predefined and custom actions.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   action: 'custom',
+ *   payload: {
+ *     type: 'analytics',
+ *     event: 'error_occurred',
+ *     category: 'authentication',
+ *     severity: 'high'
+ *   }
+ * }
+ *
+ * {
+ *   action: 'custom',
+ *   payload: {
+ *     type: 'show-modal',
+ *     modalId: 'error-modal',
+ *     title: 'Error',
+ *     message: 'Something went wrong'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+type CustomAction = {
+    action: 'custom';
+    payload?: Record<string, any>;
+};
+/**
+ * Union type of all possible error actions.
+ * Includes predefined actions (NotifyAction, LogoutAction, RedirectAction)
+ * and CustomAction for application-specific actions.
+ *
+ * @public
+ */
+type ErrorAction = NotifyAction | LogoutAction | RedirectAction | CustomAction;
+/**
+ * Configuration options for creating an ErrorX instance.
+ * All properties are optional with sensible defaults.
+ *
+ * @public
+ */
+type ErrorXOptions = {
+    /** Technical error message (default: 'An error occurred') */
+    message?: string;
+    /** Error type/name (default: 'Error') */
+    name?: string;
+    /** Error identifier code (auto-generated from name if not provided) */
+    code?: string | number;
+    /** User-friendly message for UI display (default: undefined) */
+    uiMessage?: string | undefined;
+    /** Original error that caused this error (preserves error chain) */
+    cause?: Error | unknown;
+    /** Additional context and debugging information (default: undefined) */
+    metadata?: ErrorMetadata;
+    /** Actions to perform when this error occurs (default: undefined) */
+    actions?: ErrorAction[];
+};
+/**
+ * JSON-serializable representation of an ErrorX instance.
+ * Used for transmitting errors over network or storing in databases.
+ *
+ * @example
+ * ```typescript
+ * const serialized: SerializableError = {
+ *   name: 'AuthError',
+ *   message: 'Authentication failed.',
+ *   code: 'AUTH_FAILED',
+ *   uiMessage: 'Please check your credentials',
+ *   stack: 'Error: Authentication failed.\n    at login (auth.ts:42:15)',
+ *   metadata: { userId: 123, loginAttempt: 3 },
+ *   timestamp: '2024-01-15T10:30:45.123Z',
+ *   actions: [
+ *     { action: 'logout', payload: { clearStorage: true } }
+ *   ],
+ *   cause: {
+ *     name: 'NetworkError',
+ *     message: 'Request timeout.',
+ *     code: 'NETWORK_TIMEOUT',
+ *     // ... other error properties
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+type SerializableError = {
+    /** Error type/name */
+    name: string;
+    /** Technical error message */
+    message: string;
+    /** Error identifier code */
+    code: string;
+    /** User-friendly message for UI display */
+    uiMessage: string | undefined;
+    /** Stack trace (optional) */
+    stack?: string;
+    /** Additional context and debugging information */
+    metadata: ErrorMetadata | undefined;
+    /** ISO timestamp when error was created */
+    timestamp: string;
+    /** Actions to perform when this error occurs */
+    actions?: ErrorAction[];
+    /** Serialized cause error (for error chaining) */
+    cause?: SerializableError;
+};
+
+/**
+ * Enhanced Error class with rich metadata, type-safe error handling, and intelligent error conversion.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const error = new ErrorX({ message: 'Database connection failed' })
+ *
+ * // With full options
+ * const error = new ErrorX({
+ *   message: 'User authentication failed',
+ *   name: 'AuthError',
+ *   code: 'AUTH_FAILED',
+ *   uiMessage: 'Please check your credentials',
+ *   metadata: { userId: 123, loginAttempt: 3 }
+ * })
+ * ```
+ *
+ * @public
+ */
+declare class ErrorX extends Error {
+    /** Error identifier code, auto-generated from name if not provided */
+    readonly code: string;
+    /** User-friendly message suitable for display in UI */
+    readonly uiMessage: string | undefined;
+    /** Additional context and metadata associated with the error */
+    readonly metadata: ErrorMetadata | undefined;
+    /** Timestamp when the error was created */
+    readonly timestamp: Date;
+    /** Error actions for UI behavior and handling */
+    readonly actions: ErrorAction[] | 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)
+     *
+     * @example
+     * ```typescript
+     * // Create with full options
+     * const error = new ErrorX({
+     *   message: 'Database query failed',
+     *   name: 'DatabaseError',
+     *   code: 'DB_QUERY_FAILED',
+     *   uiMessage: 'Unable to load data. Please try again.',
+     *   metadata: { query: 'SELECT * FROM users', timeout: 5000 },
+     *   actions: [
+     *     {
+     *       action: 'notify',
+     *       payload: { targets: [HandlingTargets.TOAST] }
+     *     },
+     *     {
+     *       action: 'redirect',
+     *       payload: { redirectURL: '/dashboard', delay: 1000 }
+     *     }
+     *   ]
+     * })
+     *
+     * // Create with minimal options
+     * const simpleError = new ErrorX({ message: 'Something failed' })
+     *
+     * // Create with no options (uses defaults)
+     * const defaultError = new ErrorX()
+     * ```
+     */
+    constructor(options?: ErrorXOptions);
+    /**
+     * Returns the default error name.
+     * @returns Default error name 'Error'
+     */
+    private static getDefaultName;
+    /**
+     * Generates a default error code from the error name.
+     * Converts camelCase/PascalCase names to UPPER_SNAKE_CASE format.
+     *
+     * @param name - Error name to convert
+     * @returns Generated error code in UPPER_SNAKE_CASE format
+     *
+     * @example
+     * ```typescript
+     * generateDefaultCode('DatabaseError') // 'DATABASE_ERROR'
+     * generateDefaultCode('userAuthError') // 'USER_AUTH_ERROR'
+     * generateDefaultCode('API Timeout') // 'API_TIMEOUT'
+     * ```
+     */
+    private static generateDefaultCode;
+    /**
+     * Preserves the original error's stack trace while updating the error message.
+     * Combines the new error's message with the original error's stack trace.
+     *
+     * @param originalError - The original error whose stack to preserve
+     * @param newError - The new error whose message to use
+     * @returns Combined stack trace with new error message and original stack
+     */
+    private static preserveOriginalStack;
+    /**
+     * Cleans the stack trace by removing ErrorX internal method calls.
+     * This provides cleaner stack traces that focus on user code.
+     *
+     * @param stack - Raw stack trace to clean
+     * @returns Cleaned stack trace without ErrorX internal calls
+     */
+    private static cleanStack;
+    /**
+     * Processes an error's stack trace to trim it after a specified delimiter.
+     * Useful for removing irrelevant stack frames before a specific function.
+     *
+     * @param error - Error whose stack to process
+     * @param delimiter - String to search for in stack lines
+     * @returns Processed stack trace starting after the delimiter
+     *
+     * @example
+     * ```typescript
+     * const processed = ErrorX.processErrorStack(error, 'my-app-entry')
+     * // Returns stack trace starting after the line containing 'my-app-entry'
+     * ```
+     */
+    private static processErrorStack;
+    /**
+     * Formats error messages with proper capitalization and punctuation.
+     * Ensures consistent message formatting across all ErrorX instances.
+     *
+     * @param message - Raw error message to format (optional)
+     * @returns Formatted message with proper capitalization and punctuation
+     *
+     * @example
+     * ```typescript
+     * formatMessage('database connection failed') // 'Database connection failed.'
+     * formatMessage('user not found. please check credentials') // 'User not found. Please check credentials.'
+     * formatMessage() // 'An error occurred'
+     * ```
+     */
+    private static formatMessage;
+    /**
+     * Creates a new ErrorX instance with additional metadata merged with existing metadata.
+     * The original error properties are preserved while extending the metadata.
+     *
+     * @param additionalMetadata - Additional metadata to merge with existing metadata
+     * @returns New ErrorX instance with merged metadata
+     *
+     * @example
+     * ```typescript
+     * const error = new ErrorX({
+     *   message: 'API request failed',
+     *   metadata: { endpoint: '/users' }
+     * })
+     *
+     * const enrichedError = error.withMetadata({
+     *   retryCount: 3,
+     *   userId: 123
+     * })
+     * // Result: metadata = { endpoint: '/users', retryCount: 3, userId: 123 }
+     * ```
+     */
+    withMetadata(additionalMetadata: ErrorMetadata): ErrorX;
+    /**
+     * Type guard that checks if a value is an ErrorX instance.
+     *
+     * @param value - Value to check
+     * @returns True if value is an ErrorX instance, false otherwise
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // some operation
+     * } catch (error) {
+     *   if (ErrorX.isErrorX(error)) {
+     *     // TypeScript knows error is ErrorX
+     *     console.log(error.code, error.metadata)
+     *   }
+     * }
+     * ```
+     */
+    static isErrorX(value: unknown): value is ErrorX;
+    /**
+     * Converts unknown input into an ErrorX instance with intelligent property extraction.
+     * Handles strings, regular Error objects, API response objects, and unknown values.
+     *
+     * @param error - Value to convert to ErrorX
+     * @returns ErrorX instance with extracted properties
+     *
+     * @example
+     * ```typescript
+     * // Convert string error
+     * const error1 = ErrorX.toErrorX('Something went wrong')
+     *
+     * // Convert regular Error
+     * const error2 = ErrorX.toErrorX(new Error('Database failed'))
+     *
+     * // Convert API response object
+     * const apiError = {
+     *   message: 'User not found',
+     *   code: 'USER_404',
+     *   statusText: 'Not Found'
+     * }
+     * const error3 = ErrorX.toErrorX(apiError)
+     * ```
+     */
+    static toErrorX(error: unknown): ErrorX;
+    /**
+     * Public wrapper for processing error stack traces with delimiter.
+     * Delegates to the private processErrorStack method for implementation.
+     *
+     * @param error - Error whose stack to process
+     * @param delimiter - String to search for in stack lines
+     * @returns Processed stack trace starting after the delimiter
+     *
+     * @example
+     * ```typescript
+     * const error = new Error('Something failed')
+     * const cleanStack = ErrorX.processStack(error, 'my-app-entry')
+     * // Returns stack trace starting after the line containing 'my-app-entry'
+     * ```
+     */
+    static processStack(error: Error, delimiter: string): string;
+    /**
+     * Creates a new ErrorX instance with cleaned stack trace using the specified delimiter.
+     * Returns the same instance if no delimiter is provided or no stack is available.
+     *
+     * @param delimiter - Optional string to search for in stack lines
+     * @returns New ErrorX instance with cleaned stack trace, or the same instance if no cleaning needed
+     *
+     * @example
+     * ```typescript
+     * const error = new ErrorX({ message: 'Database error' })
+     * const cleanedError = error.cleanStackTrace('database-layer')
+     * // Returns new ErrorX with stack trace starting after 'database-layer'
+     * ```
+     */
+    cleanStackTrace(delimiter?: string): ErrorX;
+    /**
+     * Converts the ErrorX instance to a detailed string representation.
+     * Includes error name, message, code, timestamp, metadata, and stack trace.
+     *
+     * @returns Formatted string representation of the error
+     *
+     * @example
+     * ```typescript
+     * const error = new ErrorX({
+     *   message: 'Database connection failed',
+     *   name: 'DatabaseError',
+     *   code: 'DB_CONN_FAILED',
+     *   metadata: { host: 'localhost', port: 5432 }
+     * })
+     *
+     * console.log(error.toString())
+     * // Output: "DatabaseError: Database connection failed. [DB_CONN_FAILED] (2024-01-15T10:30:45.123Z) metadata: {...}"
+     * ```
+     */
+    toString(): string;
+    /**
+     * Serializes the ErrorX instance to a JSON-compatible object.
+     * Recursively serializes the error chain and handles ErrorX or regular Error causes.
+     *
+     * @returns Serializable object representation of the error
+     *
+     * @example
+     * ```typescript
+     * const error = new ErrorX({
+     *   message: 'API request failed',
+     *   code: 'API_ERROR',
+     *   metadata: { endpoint: '/users', status: 500 }
+     * })
+     *
+     * const serialized = error.toJSON()
+     * // Can be safely passed to JSON.stringify() or sent over network
+     * ```
+     */
+    toJSON(): SerializableError;
+    /**
+     * Deserializes a JSON object back into an ErrorX instance.
+     * Recursively reconstructs the error chain and restores all properties.
+     *
+     * @param serialized - Serialized error object to deserialize
+     * @returns Reconstructed ErrorX instance with restored properties
+     *
+     * @example
+     * ```typescript
+     * const serializedError = {
+     *   name: 'DatabaseError',
+     *   message: 'Connection failed.',
+     *   code: 'DB_CONN_FAILED',
+     *   uiMessage: 'Database is temporarily unavailable',
+     *   metadata: { host: 'localhost' },
+     *   timestamp: '2024-01-15T10:30:45.123Z'
+     * }
+     *
+     * const error = ErrorX.fromJSON(serializedError)
+     * // Fully restored ErrorX instance with all properties
+     * ```
+     */
+    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 };