Synopsis

Why?

There are several libraries that already do this, but most of them either only support a very limited number of status codes, don't capture stack traces correctly or are no longer maintained.

The biggest difference in httperr is that it lets you attach relevant information for the error in a single function call, allowing you to separate your error handling and error response logic without losing the semantics of HTTP status codes.

Install

With NPM

npm install httperr

From source

git clone https://github.com/pluma/httperr.git

cd httperr

npm install

Basic usage example

var httperr =require('httperr');

var err = httperr[404]('The path "/example" could not be resolved');

console.log(err);

/*

{ [NotFound: The path "/example" could not be resolved]

title: 'Not Found',

name: 'NotFound',

code: 'NOT_FOUND',

statusCode: 404,

message: 'The path "/example" could not be resolved'

}

*/

throw err;

/*

NotFound: The path "/example" could not be resolved

at ...

*/

console.log(httperr.methodNotAllowed({allowed:['GET','POST']}));

/*

{ [MethodNotAllowed]

title: 'Method Not Allowed',

name: 'MethodNotAllowed',

code: 'METHOD_NOT_ALLOWED',

statusCode: 405,

message: '',

allowed: ['GET', 'POST']

}

*/

err =newhttperr.NotFound();

console.log(err);

/*

{ [NotFound]

title: 'Not Found',

name: 'NotFound',

code: 'NOT_FOUND',

statusCode: 404,

message: 'The path "/example" could not be resolved'

}

*/

console.log(err instanceofhttperr.NotFound);// true

console.log(err instanceofhttperr.notFound);// true

console.log(err instanceof httperr['404']);// true

console.log(err instanceofhttperr.MethodNotAllowed);// false

console.log(err instanceofhttperr.HttpError);// true

console.log(err instanceof Error);// true

API

new httperr.{ErrorName}([config, [extra:Object]]):Error

Creates an Error object. The new keyword is optional.

Example:

newhttperr.NotFound({message:'That does not exist'});

If extra is given and is an object, its properties will be copied to the new Error object before config is applied.

If config is a string, it will be treated as config.message.

If config is an Error object, it will be treated as config.cause.

If config is an object, it can have the following properties:

config.message (optional)

A descriptive human-readable title describing the error's cause.

config.cause (optional)

The underlying exception that caused the HTTP error.

config.details (optional)

A detailed human-readable description of the error's cause and possible solutions.

config.allowed (optional)

The methods allowed for this URL.

This property is only available for 405 Method Not Allowed errors and can be used to populate the Allow header.

config.retryAfter (optional)

The minimum delay before the request should be attempted again.

This property is only available for 429 Too Many Requests and 420 Enhance Your Calm (Twitter API) errors and can be used to populate the Retry-After header.

config.parameters (optional)

The parameters with which the request should be retried.

This property is only available for 449 Retry With (Microsoft) errors and can be used to populate the response status message.

config.location (optional)

The location for which the request should be repeated.

This property is only available for 451 Redirect (Microsoft) errors and can be used to populate the proprietary X-MS-Location response header.

title

A human-readable title for the HTTP error.

status

The HTTP response status code for the HTTP error.

init (optional)

A function which will be invoked as a method of the new error with the config argument immediately after the error is created by the factory. Can be used to process additional error-specific configuration parameters.

new httperr.HttpError(config)

The base type for all httperr error types. You probably don't want to use this directly.

httperr.HttpError::toObject([skip…]):Object

skip (optional)

One or more strings or regular expressions against which the property names of Error objects including httperr errors will be matched. Any matching properties will not be copied to the returned object.