yhttperror/README.md

Better HTTP errors for your NodeJS server.

[//]: # ( )
[//]: # (This file is automatically generated by a `metapak`)
[//]: # (module. Do not change it  except between the)
[//]: # (`content:start/end` flags, your changes would)
[//]: # (be overridden.)
[//]: # ( )
# yhttperror
> Better HTTP errors for your NodeJS server.

[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nfroidure/yhttperror/blob/main/LICENSE)
[![Coverage Status](https://coveralls.io/repos/github/git://github.com/nfroidure/yhttperror.git/badge.svg?branch=main)](https://coveralls.io/github/git://github.com/nfroidure/yhttperror.git?branch=main)


[//]: # (::contents:start)

## Usage

As a child constructor of the YError one, YHTTPError allow you to get more
 valuable errors for better debugging, even for production errors.

YHTTPError also allows you to specify an HTTP error code, with 500 as a fallback.
 Here is a sample use case near to how we use it at SimpliField:

```js
import YHTTPError from 'yhttperror';

app.put('/users/:user_id', function(req, res, next) {
  // Let's start a Promise chain
  Promise.resolve()
  // This validate the payload an could throw errors
  .then(checkUserUpdatePayload.bind(null, req.body))
  // wrap any error into an HTTP 400 error with debug params
  .catch(function wrapUserPayloadError(err) {
    throw YHTTPError.wrap(err, 400, 'E_BAD_PAYLOAD', req.params.user_id, req.body);
  })
  // This check rights an return the result
  .then(checkUserRights.bind(null, req.user._id, 'USER_UPDATE'))
  // throw a YHTTPError if the user can't update an user
  .then(throwIfNotAuthorized(authorized) {
    if(!authorized) {
      throw new YHTTPError(401, 'E_UNAUTHORIZED', 'USER_UPDATE', authorized);
    }
  })
  // This update the user in the database
  .then(updateUser.bind(null, req.params.user_id, req.body))
  // wrap the error only if it is not yet a YHTTPError, in this case, db errors
  .catch(function castDatabaseError(err) {
    throw YHTTPError.cast(err, 500, 'E_DB_ERROR');
  })
  .then(sendUser.bind(null, res))
  .catch(function sendError(err) {
    // Sending the error, better done in an error middleware but keeping things
    // simple here. We're just passing the error to next like this in production
    // code: .catch(next);
    res.status(err.httpCode).send(err.stack);
  });
});
```

The above would give you valuable errors like this:
```
// Sample payload error:
// YError: E_INVALID_PROPERTY ('name', undefined)
//    at validateUser (/validateUser.js:5:11)
//    (...)
// YHTTPError [400]: E_BAD_PAYLOAD ('abbacacaabbacacaabbacaca', { email: 'a@a.com' })
//    at Function.YHTTPError.wrap (/home/nfroidure/simplifield/yhttperror/src/index.js:41:12)
//    at /home/nfroidure/simplifield/yhttperror/test.js:16:21
//    (...)

// Sample right error:
// YHTTPError [401]: E_UNAUTHORIZED ('b17eb17eb17eb17eb17eb17e', 'USER_UPDATE')
//    at Function.YHTTPError.wrap (/home/nfroidure/simplifield/yhttperror/src/index.js:41:12)
//    at /home/nfroidure/simplifield/yhttperror/test.js:16:21
//    (...)

// Sample db error:
// Error: Cannot connect to database
//    at dbConnect (/db.js:5:11)
//    (...)
// YHTTPError [500]: E_DB_ERROR ()
//    at Function.YHTTPError.wrap (/home/nfroidure/simplifield/yhttperror/src/index.js:41:12)
//    at /home/nfroidure/simplifield/yhttperror/test.js:16:21
//    (...)
```

[//]: # (::contents:end)

# API
<a name="YHTTPError"></a>

## YHTTPError ⇐ <code>Error</code>
Class representing an HTTP Error with extra debug informations

**Kind**: global class  
**Extends**: <code>Error</code>, <code>YError</code>  

* [YHTTPError](#YHTTPError) ⇐ <code>Error</code>
    * [new YHTTPError(httpCode, [errorCode], [...params])](#new_YHTTPError_new)
    * [.wrap(err, httpCode, [errorCode], [...params])](#YHTTPError.wrap) ⇒ [<code>YHTTPError</code>](#YHTTPError)
    * [.cast(err, httpCode, [errorCode], [...params])](#YHTTPError.cast) ⇒ [<code>YHTTPError</code>](#YHTTPError)
    * [.bump(err, httpCode, [errorCode], [...params])](#YHTTPError.bump) ⇒ [<code>YHTTPError</code>](#YHTTPError)

<a name="new_YHTTPError_new"></a>

### new YHTTPError(httpCode, [errorCode], [...params])
Creates a new YHTTPError with an HTTP error code, an
 error code and some params as debug values.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| httpCode | <code>number</code> | <code>500</code> | The HTTP error code corresponding to the actual error |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [...params] | <code>any</code> |  | Some additional debugging values |

<a name="YHTTPError.wrap"></a>

### YHTTPError.wrap(err, httpCode, [errorCode], [...params]) ⇒ [<code>YHTTPError</code>](#YHTTPError)
Wraps any error and output a YHTTPError with an HTTP
 error code, an error code and some params as debug values.

**Kind**: static method of [<code>YHTTPError</code>](#YHTTPError)  
**Returns**: [<code>YHTTPError</code>](#YHTTPError) - The wrapped error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| err | <code>Error</code> |  | The error to wrap |
| httpCode | <code>number</code> |  | The HTTP error code corresponding to the actual error |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [...params] | <code>any</code> |  | Some additional debugging values |

<a name="YHTTPError.cast"></a>

### YHTTPError.cast(err, httpCode, [errorCode], [...params]) ⇒ [<code>YHTTPError</code>](#YHTTPError)
Return YHTTPError as is or wraps any other error and output
 a YHTTPError with an HTTP error code, an
 error code and some params as debug values.

**Kind**: static method of [<code>YHTTPError</code>](#YHTTPError)  
**Returns**: [<code>YHTTPError</code>](#YHTTPError) - The wrapped error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| err | <code>Error</code> |  | The error to cast |
| httpCode | <code>number</code> |  | The HTTP error code corresponding to the actual error |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [...params] | <code>any</code> |  | Some additional debugging values |

<a name="YHTTPError.bump"></a>

### YHTTPError.bump(err, httpCode, [errorCode], [...params]) ⇒ [<code>YHTTPError</code>](#YHTTPError)
Same than `YHTTPError.wrap()` but preserves the HTTP code,
 the error code and the debug values of the error if it is
 already an instance of the YHTTPError constructor.

**Kind**: static method of [<code>YHTTPError</code>](#YHTTPError)  
**Returns**: [<code>YHTTPError</code>](#YHTTPError) - The wrapped error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| err | <code>Error</code> |  | The error to bump |
| httpCode | <code>number</code> |  | The HTTP error code corresponding to the actual error |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [...params] | <code>any</code> |  | Some additional debugging values |


# Authors
- [Nicolas Froidure (formerly at Simplifield)](http://insertafter.com/en/index.html)

# License
[MIT](https://github.com/nfroidure/yhttperror/blob/main/LICENSE)