Napolean Paced Mischeviously

    @brycemarshall/exception
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.4 • Public • Published

    @brycemarshall/exception

    An extensible Typescript library of error types implementing the standard ECMAScript Error interface.

    See also @brycemarshall/simple-exception (https://www.npmjs.com/package/@brycemarshall/simple-exception) which is a lighter-weight package which may be better suited to some redistributable packages and yet which remains compatible with this fully-featured library.

    Installation

    npm install @brycemarshall/exception

    The module exports the following types:

    import { SimpleException } from '@brycemarshall/simple-exception';
    /**
     * A convenience class which exposes static factory methods for constructing common typed error instances.
     */
    export declare class ExceptionFactory {
        /**
         * Creates a new ApplicationException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
         */
        static Application(message?: string, ...args: any[]): ApplicationException;
        /**
         * Creates a new ArgumentException instance.
         * @param parameterName The name of the invalid parameter.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
         */
        static Argument(parameterName: string, message?: string, ...args: any[]): ArgumentException;
        /**
         * Creates a new ArgumentNullException instance.
         * @param parameterName The name of the null parameter.
         */
        static ArgumentNull(parameterName: string): ArgumentNullException;
        /**
         * Creates a new ArgumentOutOfRangeException instance.
         * @param parameterName The name of the invalid parameter.
         * @param min The optional value of the lower inclusive boundary of the allowable range.
         * @param max The optional value of the upper inclusive boundary of the allowable range.
         */
        static ArgumentOutOfRange(parameterName: string, min?: any, max?: any): ArgumentOutOfRangeException;
        /**
         * Creates a new InvalidOperationException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
         */
        static InvalidOperation(message?: string, ...args: any[]): InvalidOperationException;
        /**
         * Creates a new NotSupportedException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
         */
        static NotSupported(message?: string, ...args: any[]): NotSupportedException;
        /**
         * Creates a new IOException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
         */
        static IO(message?: string, ...args: any[]): IOException;
        /**
         * Creates a new TimeoutException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
         */
        static Timeout(message?: string, ...args: any[]): TimeoutException;
        /**
         * Creates a new Exception instance with the implied type specified by the errorName parameter.
         * @param errorName The name (implied type) of the Error object implemented by this instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
         */
        static Custom(errorName: string, message?: string, ...args: any[]): Exception;
    }
    /**
     * The base class for custom error types implementing the standard ECMAScript Error interface.
     * Instances of this type may be instantiated directly (without subclassing) in order to create custom error instances.
     */
    export declare class Exception extends SimpleException {
        /**
         * Creates a new Exception instance.
         * @param errorName The name (implied type) of the Error object implemented by this instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(errorName: string, message?: string, ...args: any[]);
        /**
         * Converts an Error object into an Exception if it is not already.
         * @param error The Error object to convert.
         */
        static convert(error: Error): Exception;
        /**
         * Returns true if the specified instance is an Error object, otherwise returns false.
         * @param value The value to test.
         */
        static isError(value: any): boolean;
        /**
         * Returns true if the specified instance is an Error object of the specified type, otherwise returns false.
         * @param value The value to test.
         */
        static isErrorOfType(value: any, errorName: string): boolean;
        /**
         * Returns true if the specified instance is an Exception object of the specified type, otherwise returns false.
         * @param value The value to test.
         */
        static isExceptionOfType(value: any, errorName: string): boolean;
        /**
         * Returns true if the specified instance is an Exception object, otherwise returns false.
         */
        static isException(value: any): boolean;
    }
    /**
     * An error type representing a general purpose application error.
     */
    export declare class ApplicationException extends Exception {
        /**
         * Creates a new ApplicationException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(message?: string, ...args: any[]);
        /**
         * Always returns true.
         */
        readonly isApplicationException: boolean;
    }
    /**
     * The base class for argument exception types.
     */
    export declare abstract class ArgumentExceptionBase extends Exception {
        private _pname;
        /**
         * Creates a new ArgumentException instance.
         * @param errorName The name (implied type) of the Error object implemented by this instance.
         * @param parameterName The name of the invalid parameter.
         * @param defaultMessage The default message describing the problem with the parameter.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(errorName: string, defaultMessage: string, parameterName: string, message?: string, ...args: any[]);
        /**
         * Returns the name of the invalid parameter.
         */
        readonly parameterName: string;
    }
    /**
     * The error raised when an invalid argument is passed to a function.
     */
    export declare class ArgumentException extends ArgumentExceptionBase {
        /**
         * Creates a new ArgumentException instance.
         * @param parameterName The name of the invalid parameter.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(parameterName: string, message?: string, ...args: any[]);
        /**
         * Always returns true.
         */
        readonly isArgumentException: boolean;
    }
    /**
     * The error raised when an argument with a null value is illegally passed to a function.
     */
    export declare class ArgumentNullException extends ArgumentExceptionBase {
        /**
         * Creates a new ArgumentNullException instance.
         * @param parameterName The name of the null parameter.
        */
        constructor(parameterName: string);
        /**
         * Always returns true.
         */
        readonly isArgumentNullException: boolean;
    }
    /**
     * The error raised when an argument passed to a function is outside of the legal range of allowable values required by the function.
     */
    export declare class ArgumentOutOfRangeException extends ArgumentExceptionBase {
        /**
         * Creates a new ArgumentOutOfRangeException instance.
         * @param parameterName The name of the invalid parameter.
         * @param min The optional value of the lower inclusive boundary of the allowable range.
         * @param max The optional value of the upper inclusive boundary of the allowable range.
        */
        constructor(parameterName: string, min?: any, max?: any);
        private static formatBound(value);
        /**
         * Always returns true.
         */
        readonly isArgumentOutOfRangeException: boolean;
    }
    /**
     * The error raised when a requested operation is not valid due to the state of the implementing object when the operation was initiated.
     */
    export declare class InvalidOperationException extends Exception {
        /**
         * Creates a new InvalidOperationException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(message?: string, ...args: any[]);
        /**
         * Always returns true.
         */
        readonly isInvalidOperationException: boolean;
    }
    /**
     * The error raised when a requested operation is not supported by the implementing object.
     */
    export declare class NotSupportedException extends Exception {
        /**
         * Creates a new NotSupportedException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(message?: string, ...args: any[]);
        /**
         * Always returns true.
         */
        readonly isNotSupportedException: boolean;
    }
    /**
     * The error raised when an IO error has occurred.
     */
    export declare class IOException extends Exception {
        /**
         * Creates a new IOException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(message?: string, ...args: any[]);
        /**
         * Always returns true.
         */
        readonly isIOException: boolean;
    }
    /**
     * The error raised when an operation times-out before completing.
     */
    export declare class TimeoutException extends Exception {
        /**
         * Creates a new TimeoutException instance.
         * @param message An optional error message (which may be a string formatting template).
         * @param args Optional format arguments to be applied to a string formatting template specified in 'message'.
        */
        constructor(message?: string, ...args: any[]);
        /**
         * Always returns true.
         */
        readonly isTimeoutException: boolean;
    }

    Usage - ExceptionFactory

    import { ExceptionFactory } from '@brycemarshall/exception';
    
    throw ExceptionFactory.Application();
    throw ExceptionFactory.Application("An error occurred");
    throw ExceptionFactory.InvalidOperation();
    throw ExceptionFactory.InvalidOperation("You shouldn't have done that");
    throw ExceptionFactory.NotSupported();
    throw ExceptionFactory.NotSupported("The rotate Widget operation is not supported");
    throw ExceptionFactory.Argument("param1");
    throw ExceptionFactory.ArgumentNull("param1");
    throw ExceptionFactory.ArgumentOutOfRange("param1", 1, 10);
    throw ExceptionFactory.ArgumentOutOfRange("param1", "a", "z");
    throw ExceptionFactory.ArgumentNull("param1");
    throw ExceptionFactory.IO();
    throw ExceptionFactory.IO("Writing to the Widget stream failed");
    throw ExceptionFactory.Timeout();
    throw ExceptionFactory.Timeout("Timed-out waiting for a response from the Widget");
    throw ExceptionFactory.Custom("MyCustomerErrorType");
    throw ExceptionFactory.Custom("IncompatibleFoobar", "The Foobar {0} is incompatible with the Widget {1}", "Your Foobar", "My Widget");
    throw ExceptionFactory.Custom("IncompatibleFoobar", "The Foobar {foobar} is incompatible with the Widget {widget}", { foobar: "Your Foobar", widget: "My Widget" });

    Usage - Exception classes

    Not all examples are shown.

    import { ApplicationException } from '@brycemarshall/exception';
    throw new ApplicationException("An error occurred");
    
    import { ArgumentException } from '@brycemarshall/exception';
    throw new ArgumentException("param1");
    
    import { ArgumentNullException } from '@brycemarshall/exception';
    throw new ArgumentNullException("param1");
    
    import { ArgumentOutOfRangeException } from '@brycemarshall/exception';
    throw new ArgumentOutOfRangeException("param1", 1, 10);
    
    import { Exception } from '@brycemarshall/exception';
    throw new Exception("MyCustomerErrorType");
    throw new Exception("IncompatibleFoobar", "The Foobar {0} is incompatible with the Widget {1}", "Your Foobar", "My Widget");
    throw new Exception("IncompatibleFoobar", "The Foobar {foobar} is incompatible with the Widget {widget}", { foobar: "Your Foobar", widget: "My Widget" });

    Usage - Exception Type Identification

    try {
        throw new TimeoutException();
    }
    catch (e) {
        if (e.isTimeoutException)
            console.log("Caught a TimeoutException");
    }
    try {
        throw new TimeoutException();
    }
    catch (e) {
        if (Exception.isExceptionOfType(e, "Timeout")
            console.log("Caught a TimeoutException");
    }
    try {
        throw new CustomException("Foobar");
    }
    catch (e) {
        if (e.isFoobarException)
            console.log("Caught a FoobarException");
    }
    try {
        throw new CustomException("Foobar");
    }
    catch (e) {
        if (Exception.isExceptionOfType(e, "Foobar")
            console.log("Caught a FoobarException");
    }

    Usage - Native Error Type Identification

    try {
        throw new RangeError();
    }
    catch (e) {
        e = Exception.convert(e);
        if (e.isRangeErrorException)
            console.log("Caught an Error of type 'RangeError'");
    }
    try {
        throw new RangeError();
    }
    catch (e) {
        if (Exception.isErrorOfType(e, "RangeError")
            console.log("Caught an Error of type 'RangeError'");
    }
    try {
        throw new Error();
    }
    catch (e) {
        e = Exception.convert(e);
        if (e.isErrorException)
            console.log("Caught an Error of type 'Error'");
    }

    Contributors

    • Bryce Marshall

    MIT Licenced

    Install

    npm i @brycemarshall/exception

    DownloadsWeekly Downloads

    1

    Version

    1.1.4

    License

    MIT

    Last publish

    Collaborators

    • brycemarshall