httperr
Version:
HTTP status codes as JavaScript errors.
214 lines (151 loc) • 6.46 kB
Markdown
# Synopsis
**httperr** provides Error types for all HTTP error status codes.
[
](http://nodejs.org/api/documentation.html#documentation_stability_index) [](http://unlicense.org/) [](https://flattr.com/submit/auto?user_id=pluma&url=https://github.com/pluma/httperr)
[](https://travis-ci.org/pluma/httperr) [](https://coveralls.io/r/pluma/httperr?branch=master) [](https://david-dm.org/pluma/httperr)
[](https://npmjs.org/package/httperr)
# 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
```sh
npm install httperr
```
## From source
```sh
git clone https://github.com/pluma/httperr.git
cd httperr
npm install
```
# Basic usage example
```javascript
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 = new httperr.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 instanceof httperr.NotFound); // true
console.log(err instanceof httperr.notFound); // true
console.log(err instanceof httperr['404']); // true
console.log(err instanceof httperr.MethodNotAllowed); // false
console.log(err instanceof httperr.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:
```javascript
new httperr.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.
## httperr.{statusCode}([config, [extra:Object]]):Error
See above.
Example:
```javascript
httperr[404]({message: 'That does not exist either'});
```
## httperr.{errorName}([config, [extra:Object]]):Error
See above.
Example:
```javascript
httperr.notFound({message: 'This link is dead, too'})
```
## httperr.createHttpError(status:Number, title:String, [init:Function]):Function
Creates a new error type for the given HTTP error status.
Takes the following arguments:
### 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
Returns a JSON serializable representation of this `httperr` error (including any nested `Error` objects).
Takes the following arguments:
### 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.
Example:
```js
var err = httperr.notFound('File Not Found');
console.log(err.toObject());
/*
{
name: 'NotFound',
code: 'NOT_FOUND',
title: 'Not Found',
statusCode: 404,
message: 'File Not Found',
stack: '…'
}
*/
console.log(err.toObject('stack', /^title$/));
/*
{
name: 'NotFound',
code: 'NOT_FOUND',
statusCode: 404,
message: 'File Not Found'
}
*/
```
# Unlicense
This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying [UNLICENSE](https://github.com/pluma/httperr/blob/master/UNLICENSE) file.