amn-error v0.0.10

AMN Error

Amn Error is an extension module on top of expressjs.

Native Error class is limited and does not allow to response with specific http code and supply an error with more details.

AMN Error able to accommodate additional fields in compare to nodejs native error class.

status - HTTP status of error. Must be a valid http status code!

code - similar to node js error code which delivers internal error code.

message - is inherited from nodejs Error class.

explanation - an optional field to accommodate more details on the error nature you want to inform the client.

Amn Error gives more flexibility on declaring error back to a client.

For example, 401 - unauthorized may looks like following.

import error from 'amn-error';

throw error.create(401, 'UNAUTHORIZED', 'bad credentials');

Client receives http status code as 401 (unauthorized)

And JSON object

{
    "code": "UNAUTHORIZED",
    "message": "bad credentials"
}

How to raise and error

Amn error provides two ways to raise an error by means on bespoke AmnError Class.

import error from 'amn-error';

/**
 * Error function
 * @param status - valid HTTP status code, e.g. 4XX, 5XX, etc
 * @param code - error code, usually in capital ERROR_REASON
 * @param message - free text to explain a reason
 * @param explanation - optional extra filed to provide more derails around a nature of an error
 */

throw error.create(
    400,
    'BAD_REQUEST',
    'bad request from client',
    'invalid email'
);

throw error.create(
    404,
    'NOT_FOUND',
    'resource not found',
    'fail to find user account'
);

throw error.create(
    500,
    'INTERNAL_SERVER_ERROR',
    'critical server-side internal error'
);

On large scale services, it may be worth to pre-define errors as JSON object and pass it to error functions, rather than provide parameter by parameter.

Amn Error delivers an extra function to support a more declarative approach

import error from 'amn-error';

// pre-define error code object
const BAD_REQUEST: {
    status: 400,
    code: 'BAD_REQUEST',
    message: 'bad request from client',
};

const UNAUTHORIZED: {
    status: 401,
    code: 'UNAUTHORIZED',
    message: 'user is not authorized',
};

const INTERNAL_SERVER_ERROR: {
    status: 500,
    code: 'INTERNAL_SERVER_ERROR',
    message: 'critical server-side internal error',
};

// raise and error examples
throw error.withCode(BAD_REQUEST, 'invalid email');

throw error.withCode(UNAUTHORIZED);

throw error.withCode(INTERNAL_SERVER_ERROR);

withCode function is a proxy to error.create. It consumes the object as parameter following interface

declare interface IErrorCode {
    status: number; // valid HTTP status code, e.g. 4XX, 5XX, etc
    code: string; // error code, usually in capital ERROR_REASON
    message: string; // free text to explain a reason
}

explanation - is the second optional parameter providing more derails around the nature of error.

How use middleware

Amn Error provides two middleware. errorHandler - to handle bespoke amn error class.

defaultErrorHandler - to handle an error raised by native nodejs Error, but reply to a client with a http status code. By default status code is 500.

defaultErrorHandler provided just for compatibility with native nodejs Error class.

import error from 'amn-error';

const app = express();

app.use(error.errorHandler);

Logging errors

Amn Error middleware provide capability to perform logging by means of callback function.

errorHandler middleware accepts optional callback function.

import error from 'amn-error';
import logger from 'my-logger';

const app = express();

app.use(error.errorHandler(logger.error));