@magic.batua/error/Source/ClientError.ts

The Error module powers the error handling features of the Magic Batua.

/**
 *  @module     ClientError
 *  @overview   Defines the `ClientError` class.
 *  
 *  @author     Animesh Mishra <hello@animesh.ltd>
 *  @copyright  © 2018 Animesh Ltd. All Rights Reserved.
 */

import { Code } from "./Code"

/**
 *  The `ClientError` class represents errors whose origin lie client-side. Incorrectly formatted 
 *  requests, wrong methods used for API calls and invalid tokens are some examples of a `ClientError`. 
 *  An appropriate error information and status code is shared with the client when a `ClientError` 
 *  is thrown.
 */
export class ClientError extends Error {
    public code: Code
    public message: string
    public help?: string

    /**
     *  Initialises a `ClientError` with the given HTTP status code, the error message and
     *  an optional debugging help text.
     *  
     *  @param { Code } code        HTTP status code for the error response 
     *  @param { string } message   The error message
     *  @param { string } help      Optional debugging help text
     *  
     *  @constructor
     */
    public constructor(code: Code, message: string, help?: string) {
        super()
        this.code    = code
        this.message = message
        this.help    = help
    }

    /**
     *  Sanitises a `ClientError` object by getting rid of the `code` property. Sending the
     *  `code` property client-side could make the impression that client shouldn't pay 
     *  attention to the HTTP response's `status` header and should code against the response 
     *  body's `code` property instead. That would be a bad design choice.
     * 
     *  @returns { any } A `ClientError` object without the `code`.
     * 
     *  @function Export
     *  @memberof ClientError
     *  @instance
     */
    public Export(): any {
        let publicView = JSON.parse(JSON.stringify(this))
        delete publicView.code
        return publicView
    }
}