@aedart/support/dist/types/exceptions.d.ts

The Ion support package

/**
 * @aedart/support
 * 
 * BSD-3-Clause, Copyright (c) 2023-present Alin Eugen Deac <aedart@gmail.com>.
 */

import { AbstractConstructor } from '@aedart/contracts';
import { Throwable } from '@aedart/contracts/support/exceptions';

/**
 * Logical Error
 *
 * To be thrown whenever there is an error in the programming logic.
 *
 * This error is inspired by PHP's [`LogicException`]{@link https://www.php.net/manual/en/class.logicexception}
 */
declare class LogicalError extends Error implements Throwable {
    /**
     * Create a new logical error instance
     *
     * @param {string} [message]
     * @param {ErrorOptions} [options]
     */
    constructor(message?: string, options?: ErrorOptions);
}

/**
 * Abstract Class Error
 *
 * To be thrown whenever an abstract class is attempted instantiated directly.
 */
declare class AbstractClassError extends LogicalError {
    /**
     * The abstract class that was attempted instantiated
     *
     * @type {AbstractConstructor}
     */
    target: AbstractConstructor;
    /**
     * Create new instance of Abstract Class Error
     *
     * @param {AbstractConstructor} target The abstract class that was attempted instantiated directly
     * @param {ErrorOptions} [options]
     */
    constructor(target: AbstractConstructor, options?: ErrorOptions);
}

/**
 * Configures the custom error
 *
 * **Note**: _Method sets the custom error's name and optionally captures a [stack trace]{@link configureStackTrace}
 * and sets it as the custom error's stack._
 *
 * **Example**:
 * ```
 * class MyCustomError extends Error
 * {
 *      constructor(message, options)
 *      {
 *          super(message, options)
 *
 *          configureCustomError(this);
 *      }
 * }
 * ```
 *
 * @template T extends Error
 *
 * @param {Error} error
 * @param {boolean} [captureStackTrace=false]
 *
 * @return {Error}
 */
declare function configureCustomError<T extends Error>(error: T, captureStackTrace?: boolean): T;

/**
 * Captures stack trace and sets stack trace for given error
 *
 * **Caution**: _Method will mutate given `error` by setting the `stack` property_
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types
 *
 * @param {Error} error
 *
 * @return {string|undefined} Captured stack trace
 */
declare function configureStackTrace(error: Error): string | undefined;

/**
 * Returns error message from {@link Error}, if possible
 *
 * @param {any} error Error or value that was thrown
 * @param {string} [defaultMessage] A default message to return if unable to resolve error message
 *
 * @return {string}
 */
declare function getErrorMessage(error: any, /* eslint-disable-line @typescript-eslint/no-explicit-any */ defaultMessage?: string): string;

export { AbstractClassError, LogicalError, configureCustomError, configureStackTrace, getErrorMessage };