koa-better-error-handler

koa-better-error-handler

A better error-handler for Lad and Koa. Makes ctx.throw awesome (best used with koa-404-handler)

Index

• Features
• Install
• Usage
  • API
  • Web App
• User-Friendly Responses
• HTML Error Lists
• License

Features

• Uses Boom for making error messages beautiful (see User Friendly Responses below)
• Simply a better error handler (doesn't remove all headers like the built-in one does)
• Doesn't make all status codes 500 (like the built-in Koa error handler does)
• Supports Flash messages and preservation of newly set session object
• Fixes annoying redirect issue where flash messages were lost upon an error being thrown
• Supports HTML Error Lists using <ul> for Mongoose validation errors with more than one message
• Makes ctx.throw beautiful messages (e.g. ctx.throw(404) will output a beautiful error object :hibiscus:)
• Supports text/html, application/json, and text response types
• Supports and recommends use of mongoose-beautiful-unique-validation

Install

npm install --save koa-better-error-handler

Usage

You should probably be using this in combination with koa-404-handler too!

API

No support for sessions, cookies, or flash messaging:

const errorHandler = require('koa-better-error-handler');
const Koa = require('koa');
const Router = require('koa-router');
const koa404Handler = require('koa-404-handler');

// initialize our app
const app = new Koa();

// override koa's undocumented error handler
app.context.onerror = errorHandler;

// specify that this is our api
app.context.api = true;

// use koa-404-handler
app.use(koa404Handler);

// set up some routes
const router = new Router();

// throw an error anywhere you want!
router.get('/404', ctx => ctx.throw(404));
router.get('/500', ctx => ctx.throw(500));

// initialize routes on the app
app.use(router.routes());

// start the server
app.listen(3000);
console.log('listening on port 3000');

Web App

Built-in support for sessions, cookies, and flash messaging:

const errorHandler = require('koa-better-error-handler');
const Koa = require('koa');
const redis = require('redis');
const RedisStore = require('koa-redis');
const session = require('koa-generic-session');
const flash = require('koa-connect-flash');
const convert = require('koa-convert');
const Router = require('koa-router');
const koa404Handler = require('koa-404-handler');

// initialize our app
const app = new Koa();

// define keys used for signing cookies
app.keys = ['foo', 'bar'];

// initialize redis store
const redisClient = redis.createClient();
redisClient.on('connect', () => app.emit('log', 'info', 'redis connected'));
redisClient.on('error', err => app.emit('error', err));

// define our storage
const redisStore = new RedisStore({
  client: redisClient
});

// add sessions to our app
app.use(
  convert(
    session({
      store: redisStore
    })
  )
);

// add support for flash messages (e.g. `req.flash('error', 'Oops!')`)
app.use(convert(flash()));

// override koa's undocumented error handler
app.context.onerror = errorHandler;

// use koa-404-handler
app.use(koa404Handler);

// set up some routes
const router = new Router();

// throw an error anywhere you want!
router.get('/404', ctx => ctx.throw(404));
router.get('/500', ctx => ctx.throw(500));

// initialize routes on the app
app.use(router.routes());

// start the server
app.listen(3000);
console.log('listening on port 3000');

User-Friendly Responses

Example Request:

curl -H "Accept: application/json" http://localhost/some-page-does-not-exist

Example Response:

{
  "statusCode": 404,
  "error": "Not Found",
  "message":"Not Found"
}

Prevent Errors From Being Automatically Translated

As of v3.0.5, you can prevent an error from being automatically translated by setting the error property of no_translate to have a value of true:

function middleware(ctx) {
  const err = Boom.badRequest('Uh oh!');
  err.no_translate = true; // <----
  ctx.throw(err);
}

HTML Error Lists

If you specify app.context.api = true or set ctx.api = true, and if a Mongoose validation error message occurs that has more than one message (e.g. multiple fields were invalid) – then err.message will be joined by a comma instead of by <li>.

Therefore if you DO want your API error messages to return HTML formatted error lists for Mongoose validation, then set app.context.api = false, ctx.api = false, or simply make sure to not set them before using this error handler.

try {
  // trigger manual validation
  // (this allows us to have a 400 error code instead of 500)
  await company.validate();
} catch (err) {
  ctx.throw(Boom.badRequest(err));
}

With error lists:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "<ul class=\"text-left mb-0\"><li>Path `company_logo` is required.</li><li>Gig description must be 100-300 characters.</li></ul>"
}

Without error lists:

{
  "statusCode":400,
  "error":"Bad Request",
  "message":"Path `company_logo` is required., Gig description must be 100-300 characters."
}

API Friendly Messages

By default if ctx.api is true, then html-to-text will be invoked upon the err.message, thus converting all the HTML markup into text format.

You can also specify a base URI in the environment variable for rendering as process.env.ERROR_HANDLER_BASE_URL, e.g. BERROR_HANDLER_BASE_URL=https://example.com (omit trailing slash), and any HTML links such as <a href="/foo/bar/baz">Click here</a> will be converted to [Click here][1] with a [1] link appended of https://example.com/foo/bar/baz.

License

MIT © Nick Baugh