# node-err
Simplify error handling and logging for Node.
## Index
+ [Overview](#overview)
+ [Technical](#technical)
+ [Examples](#examples)
## Overview
**One Error Handler**
With node-err, you always use the same error handler, giving you expected behavior...
> `nodeErr.repeat(err);`
```
const nodeErr = require('node-err');
return fetch()
.catch(err => {
return nodeErr.repeat(err);
});
```
**Bubbling-up Errors**
With consistent error handling, bubbling-up errors is super easy...
```
return fetch()
.catch(err => {
return nodeErr.repeat(err);
})
.catch(err => {
return nodeErr.repeat(err);
})
.catch(err => {
return nodeErr.repeat(err);
})
.catch(err => {
return next(err);
});
```
**Automatic logging**
And logging/reporting is a breeze, it happens automatically...
> `nodeErr.repeat(err, details);`
```
return fetchUsers()
.catch(err => {
let details = {
name: 'FETCH_USERS',
status: 500,
};
return nodeErr.repeat(err, details);
});
```
**Server Logging**
Server logging happens out-of-the-box so you can set-up alerts with a service such as Papertrail...
> `papertrail -f SERVER_ERROR`
**Custom Logging**
But you can set up your only logger too...
> `nodeErr.setup({ logger: myOwnLogger });`
**Custom Output Responses**
Configure and send response data for outputting to the browser. View the Simple Promises example to see it in action.
```
nodeErr.setup({ responses: ['user_message','internal_code'] });
return saveAnalytics()
.catch(err => {
return nodeErr.repeat(err, {
status: 500,
responses: {
user_message: 'Oops! Something went wrong.',
internal_code: '2352',
}
});
})
.catch(err => {
let statusCode = nodeErr.getStatus(err);
let outputResponse = nodeErr.getResponse(err);
return res.status(statusCode).send(outputResponse);
});
}
```
**Localized/Silent Error Handling**
Sometimes you need to handle some errors a little differently, while still allowing other errors to bubble-up or pass through...
> `nodeErr.repeat(customVal)(err);`
```
return saveAnalytics()
.then(() => {
// do more stuff with the ability to
// bubble up a different fatal error
return true;
})
.catch(err => {
// if our saveAnalytics() failed, lets
// keep going and just return false
return nodeErr.repeat(false)(err);
})
.then(result => {
// did the analytics save ok?
return (result) ? next() : retry();
});
}
```
For more details, view the [handling](#handling) sections below.
**Async/Await**
```
(async function() {
try {
throw new Error('cubitum irem');
} catch(err) {
await nodeErr.repeat(err, { name: 'Do I know latin?' });
}
})().catch(err => {
// Hey Alexa...
});
```
**Express Middleware**
How about some Express middleware to catch/report any un-reported errors?
> `nodeErr.stop(err);`
```
app.use((err, req, res, next) => {
let details = { req };
nodeErr.stop(err, details);
return next(err);
});
```
**Error Output**
What should you do with all of these errors? Whatever you like...
> `app.use((err, req, res, next) => res.sendStatus( nodeErr.getStatus(err) ));`
## Technical
**Getting Started**
Just require `node-err` and start using `repeat` to automatically log and bubble-up errors...
```
const nodeErr = require('node-err');
return fetch()
.catch(err => {
return nodeErr.repeat(err);
});
```
**Config Vars (optional)**
Call the `setup` function in your entry file (index.js or server.js) and pass config vars (optional)...
```
const nodeErr = require('node-err');
nodeErr.setup({
prefix: 'FIND_THIS_ERROR',
status: 401,
debug: true,
logger: (err) => slackChannel('Doh', err)),
responses: ['user_message'],
overrideResponses: true,
});
```
Key | Type | Description
--- | --- | ---
`prefix` | *string* | Global prefix added to all error logs.
`status` | *number* | Default HTTP status code error.
`debug` | *bool* | Output error repetition tracing.
`logger` | *func* | Custom logging function (accepts Error obj).
`responses` | *array* | Array of response properties.
`overrideResponses` | *bool* | Allow automatic overwrite of responses when bubbling up.
**Additional Error Details (optional)**
When calling `repeat` add some more details so you know what went wrong (optional)...
```
nodeErr.repeat(err, {
name: 'AWS_IMAGE_NOT_SAVED',
req: req,
status: 400,
context: { imageName: 'budget-report.ppt'},
responses: { user_message: 'Oops! Something went wrong.' },
log: false,
censor: true,
});
```
Key | Type | Description
--- | --- | ---
`name` | *string* | (optional) Custom error name.
`req` | *object* | (optional) Express request object.
`status` | *bool* | (optional) Desired http status response code.
`context` | *any* | (optional) Whatever works.
`responses` | *object* | (optional) Data to place on the response output.
`log` | *bool* | (optional) Skip logging at this repeat node (intentional errors).
`censor` | *bool* | (optional) Skip request body log (persists with bubbling up).
If `req` is provided, you'll also get access to:
+ IP Address
+ Requested URL
+ Request Body
+ Request Method
+ User Agent
Any `responses` data provided, must have its property added to the `setup` config.
**Basic Block Error Handling/Bubbling**
By default, calling `repeat` on an error the first time will create an error report and then reject it again with a `Promise.reject`.
Calling `repeat` again (in subsequent catch block) on an already reported error will just reject the same error again (no further reporting).
```
return fetch()
.then(() => Promise.reject('level 1 error please'))
.catch(err => {
return nodeErr.repeat(err, { name: 'level 1' }); // report and rejects again
})
.then(() => doSomething()
.catch(err => {
return nodeErr.repeat(err, { name: 'level 2' }); // rejects level 1 error again
})
.then(() => doSomething()
.catch(err => {
return nodeErr.repeat(err, { name: 'level 3' }); // rejects level 1 error again
})
.catch(err => {
return next(err); // returns level 1 error
});
```
In this way, errors can bubble back up and be handled however you like.
**Multi-directional Error Handling**
You might want to handle some error differently, while still allowing processes above it to pass/bubble their errors through.
By using `repeat` with a custom value, which returns a callback and accepts, you can achieve multi-directional functionality:
+ Any previously reported will continue to bubble up and through.
+ Any un-reported errors will output with whatever value you set.
In this way, you can have a silent error handler for one process without breaking promise chain for processes above/before it.
> `nodeErr.repeat('It failed!')(err);`
```
return saveAnalytics()
.then(() => {
return fetchUser();
})
.catch(err => {
// if we didnt have a db conn error, and instead had an error
// from saveAnalytics, the below would just return `false`
return nodeErr.repeat(false)(err); // our db conn error will pass through
})
.then(result => {
return (result) ? next() : retry(); // this is skipped because of our db conn error
})
.catch(err => {
return next(err); // return db conn error
})
}
function fetchUser() {
return fetch()
.then(result => {
throw new Error('remote db conn err'); // fire error
})
.then(() => true) // this is skipped
.catch(err => {
return nodeErr.repeat(err, { name: 'FETCH_USER' }); // this will reject again
})
}
```
You can also force an error report on a silent/custom error, so it will still show in the logs:
> `nodeErr.repeat('It failed!', true)(err);`
## Examples
**Viewing the Examples**
There are several examples included in the project. To run these...
1. `$ cd examples`
2. `$ npm install`
3. `$ npm run start`
4. Navigate to `http://localhost:5000` for a directory of examples.